File System Related Extensions
Direct IO
Introduction
PHP supports the direct io functions as described in the Posix Standard (Section 6) for performing I/O functions at a lower level than the C-Language stream I/O functions (fopen(), fread(),..). The use of the DIO functions should be considered only when direct control of a device is needed. In all other cases, the standard filesystem functions are more than adequate.
Note:
This extension has been moved to the » PECL repository and is no longer bundled with PHP as of PHP 5.1.0.
Installing/Configuring
Table of Contents
Requirements
No external libraries are needed to build this extension.
Installation
This » PECL extension is not bundled with PHP.
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: » https://pecl.php.net/package/dio.
A DLL for this PECL extension is currently unavailable. See also the building on Windows section.
Runtime Configuration
This extension has no configuration directives defined in php.ini.
Resource Types
One resource type is defined by this extension: a file descriptor returned by dio_open().
Predefined Constants
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
-
F_DUPFD(integer) -
F_GETFD(integer) -
F_GETFL(integer) -
F_GETLK(integer) -
F_GETOWN(integer) -
F_RDLCK(integer) -
F_SETFL(integer) -
F_SETLK(integer) -
F_SETLKW(integer) -
F_SETOWN(integer) -
F_UNLCK(integer) -
F_WRLCK(integer) -
O_APPEND(integer) -
O_ASYNC(integer) -
O_CREAT(integer) -
O_EXCL(integer) -
O_NDELAY(integer) -
O_NOCTTY(integer) -
O_NONBLOCK(integer) -
O_RDONLY(integer) -
O_RDWR(integer) -
O_SYNC(integer) -
O_TRUNC(integer) -
O_WRONLY(integer) -
S_IRGRP(integer) -
S_IROTH(integer) -
S_IRUSR(integer) -
S_IRWXG(integer) -
S_IRWXO(integer) -
S_IRWXU(integer) -
S_IWGRP(integer) -
S_IWOTH(integer) -
S_IWUSR(integer) -
S_IXGRP(integer) -
S_IXOTH(integer) -
S_IXUSR(integer)
Direct IO Functions
dio_close
(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)
dio_close — Closes the file descriptor given by fd
Description
$fd
) : void
The function dio_close() closes the file descriptor
fd.
Return Values
No value is returned.
Examples
Example #1 Closing an open file descriptor
<?php
$fd = dio_open('/dev/ttyS0', O_RDWR);
dio_close($fd);
?>
See Also
- dio_open() - Opens a file (creating it if necessary) at a lower level than the C library input/ouput stream functions allow
dio_fcntl
(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)
dio_fcntl — Performs a c library fcntl on fd
Description
The dio_fcntl() function performs the
operation specified by cmd on the file
descriptor fd. Some commands require
additional arguments args to be supplied.
Parameters
-
fd -
The file descriptor returned by dio_open().
-
cmd -
Can be one of the following operations:
-
F_SETLK- Lock is set or cleared. If the lock is held by someone else dio_fcntl() returns -1. -
F_SETLKW- likeF_SETLK, but in case the lock is held by someone else, dio_fcntl() waits until the lock is released. -
F_GETLK- dio_fcntl() returns an associative array (as described below) if someone else prevents lock. If there is no obstruction key "type" will set toF_UNLCK. -
F_DUPFD- finds the lowest numbered available file descriptor greater than or equal toargsand returns them. -
F_SETFL- Sets the file descriptors flags to the value specified byargs, which can beO_APPEND,O_NONBLOCKorO_ASYNC. To useO_ASYNCyou will need to use the PCNTL extension.
-
-
args -
argsis an associative array, whencmdisF_SETLKorF_SETLLW, with the following keys:-
start- offset where lock begins -
length- size of locked area. zero means to end of file -
whence- Where l_start is relative to: can beSEEK_SET,SEEK_ENDandSEEK_CUR -
type- type of lock: can beF_RDLCK(read lock),F_WRLCK(write lock) orF_UNLCK(unlock)
-
Return Values
Returns the result of the C call.
Examples
Example #1 Setting and clearing a lock
<?php
$fd = dio_open('/dev/ttyS0', O_RDWR);
if (dio_fcntl($fd, F_SETLK, Array("type"=>F_WRLCK)) == -1) {
// the file descriptor appears locked
echo "The lock can not be cleared. It is held by someone else.";
} else {
echo "Lock successfully set/cleared";
}
dio_close($fd);
?>
Notes
Note: This function is not implemented on Windows platforms.
dio_open
(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)
dio_open — Opens a file (creating it if necessary) at a lower level than the C library input/ouput stream functions allow
Description
$filename
, int $flags
[, int $mode = 0
] ) : resourcedio_open() opens a file and returns a new file descriptor for it.
Parameters
-
filename -
The pathname of the file to open.
-
flags -
The
flagsparameter is a bitwise-ORed value comprising flags from the following list. This value must include one ofO_RDONLY,O_WRONLY, orO_RDWR. Additionally, it may include any combination of the other flags from this list.-
O_RDONLY- opens the file for read access. -
O_WRONLY- opens the file for write access. -
O_RDWR- opens the file for both reading and writing. -
O_CREAT- creates the file, if it doesn't already exist. -
O_EXCL- if bothO_CREATandO_EXCLare set and the file already exists, dio_open() will fail. -
O_TRUNC- if the file exists and is opened for write access, the file will be truncated to zero length. -
O_APPEND- write operations write data at the end of the file. -
O_NONBLOCK- sets non blocking mode. -
O_NOCTTY- prevent the OS from assigning the opened file as the process's controlling terminal when opening a TTY device file.
-
-
mode -
If
flagscontainsO_CREAT,modewill set the permissions of the file (creation permissions).modeis required for correct operation whenO_CREATis specified inflagsand is ignored otherwise.The actual permissions assigned to the created file will be affected by the process's umask setting as per usual.
Return Values
A file descriptor or FALSE on error.
Examples
Example #1 Opening a file descriptor
<?php
$fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);
dio_close($fd);
?>
dio_read
(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)
dio_read — Reads bytes from a file descriptor
Description
$fd
[, int $len = 1024
] ) : string
The function dio_read() reads and returns
len bytes from file with descriptor
fd.
Parameters
-
fd -
The file descriptor returned by dio_open().
-
len -
The number of bytes to read. If not specified, dio_read() reads 1K sized block.
Return Values
The bytes read from fd.
dio_seek
(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)
dio_seek — Seeks to pos on fd from whence
Description
$fd
, int $pos
[, int $whence = SEEK_SET
] ) : intThe function dio_seek() is used to change the file position of the given file descriptor.
Parameters
-
fd -
The file descriptor returned by dio_open().
-
pos -
The new position.
-
whence -
Specifies how the position
posshould be interpreted:-
SEEK_SET(default) - specifies thatposis specified from the beginning of the file. -
SEEK_CUR- Specifies thatposis a count of characters from the current file position. This count may be positive or negative. -
SEEK_END- Specifies thatposis a count of characters from the end of the file. A negative count specifies a position within the current extent of the file; a positive count specifies a position past the current end. If you set the position past the current end, and actually write data, you will extend the file with zeros up to that position.
-
Return Values
Examples
Example #1 Positioning in a file
<?php
$fd = dio_open('/dev/ttyS0', O_RDWR);
dio_seek($fd, 10, SEEK_SET);
// position is now at 10 characters from the start of the file
dio_seek($fd, -2, SEEK_CUR);
// position is now at 8 characters from the start of the file
dio_seek($fd, -5, SEEK_END);
// position is now at 5 characters from the end of the file
dio_seek($fd, 10, SEEK_END);
// position is now at 10 characters past the end of the file.
// The 10 characters between the end of the file and the current
// position are filled with zeros.
dio_close($fd);
?>
dio_stat
(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)
dio_stat — Gets stat information about the file descriptor fd
Description
$fd
) : arraydio_stat() returns information about the given file descriptor.
Return Values
Returns an associative array with the following keys:
-
"device" - device
-
"inode" - inode
-
"mode" - mode
-
"nlink" - number of hard links
-
"uid" - user id
-
"gid" - group id
-
"device_type" - device type (if inode device)
-
"size" - total size in bytes
-
"blocksize" - blocksize
-
"blocks" - number of blocks allocated
-
"atime" - time of last access
-
"mtime" - time of last modification
-
"ctime" - time of last change
NULL.
dio_tcsetattr
(PHP 4 >= 4.3.0, PHP 5 < 5.1.0)
dio_tcsetattr — Sets terminal attributes and baud rate for a serial port
Description
$fd
, array $options
) : bool
dio_tcsetattr() sets the terminal attributes and baud
rate of the open fd.
Parameters
-
fd -
The file descriptor returned by dio_open().
-
options -
The currently available options are:
-
'baud' - baud rate of the port - can be 38400,19200,9600,4800,2400,1800, 1200,600,300,200,150,134,110,75 or 50, default value is 9600.
-
'bits' - data bits - can be 8,7,6 or 5. Default value is 8.
-
'stop' - stop bits - can be 1 or 2. Default value is 1.
-
'parity' - can be 0,1 or 2. Default value is 0.
-
Return Values
No value is returned.
Examples
Example #1 Setting the baud rate on a serial port
<?php
$fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);
dio_fcntl($fd, F_SETFL, O_SYNC);
dio_tcsetattr($fd, array(
'baud' => 9600,
'bits' => 8,
'stop' => 1,
'parity' => 0
));
while (1) {
$data = dio_read($fd, 256);
if ($data) {
echo $data;
}
}
?>
Notes
Note: This function is not implemented on Windows platforms.
dio_truncate
(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)
dio_truncate — Truncates file descriptor fd to offset bytes
Description
$fd
, int $offset
) : bool
dio_truncate() truncates a file to at most
offset bytes in size.
If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is unspecified whether the file is left unchanged or is extended. In the latter case the extended part reads as zero bytes.
Return Values
Returns TRUE on success or FALSE on failure.
Notes
Note: This function is not implemented on Windows platforms.
dio_write
(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)
dio_write — Writes data to fd with optional truncation at length
Description
$fd
, string $data
[, int $len = 0
] ) : int
dio_write() writes up to len
bytes from data to file fd.
Parameters
-
fd -
The file descriptor returned by dio_open().
-
data -
The written data.
-
len -
The length of data to write in bytes. If not specified, the function writes all the data to the specified file.
Return Values
Returns the number of bytes written to fd.
Table of Contents
- dio_close — Closes the file descriptor given by fd
- dio_fcntl — Performs a c library fcntl on fd
- dio_open — Opens a file (creating it if necessary) at a lower level than the C library input/ouput stream functions allow
- dio_read — Reads bytes from a file descriptor
- dio_seek — Seeks to pos on fd from whence
- dio_stat — Gets stat information about the file descriptor fd
- dio_tcsetattr — Sets terminal attributes and baud rate for a serial port
- dio_truncate — Truncates file descriptor fd to offset bytes
- dio_write — Writes data to fd with optional truncation at length
- Introduction
- Installing/Configuring
- Predefined Constants
- Direct IO Functions
- dio_close — Closes the file descriptor given by fd
- dio_fcntl — Performs a c library fcntl on fd
- dio_open — Opens a file (creating it if necessary) at a lower level than the C library input/ouput stream functions allow
- dio_read — Reads bytes from a file descriptor
- dio_seek — Seeks to pos on fd from whence
- dio_stat — Gets stat information about the file descriptor fd
- dio_tcsetattr — Sets terminal attributes and baud rate for a serial port
- dio_truncate — Truncates file descriptor fd to offset bytes
- dio_write — Writes data to fd with optional truncation at length
Directories
Installing/Configuring
Table of Contents
Requirements
No external libraries are needed to build this extension.
Installation
There is no installation needed to use these functions; they are part of the PHP core.
Runtime Configuration
This extension has no configuration directives defined in php.ini.
Resource Types
This extension has no resource types defined.
Predefined Constants
The Directory class
(PHP 4, PHP 5, PHP 7)
Introduction
Instances of Directory are created by calling the dir() function, not by the new operator.
Class synopsis
Properties
- path
-
The directory that was opened.
- handle
-
Can be used with other directory functions such as readdir(), rewinddir() and closedir().
Directory::close
(PHP 4, PHP 5, PHP 7)
Directory::close — Close directory handle
Description
$dir_handle
] ) : void
Same as closedir(), only
dir_handle defaults to $this->handle.
Directory::read
(PHP 4, PHP 5, PHP 7)
Directory::read — Read entry from directory handle
Description
$dir_handle
] ) : string
Same as readdir(), only
dir_handle defaults to $this->handle.
Directory::rewind
(PHP 4, PHP 5, PHP 7)
Directory::rewind — Rewind directory handle
Description
$dir_handle
] ) : void
Same as rewinddir(), only
dir_handle defaults to $this->handle.
Table of Contents
- Directory::close — Close directory handle
- Directory::read — Read entry from directory handle
- Directory::rewind — Rewind directory handle
Directory Functions
See Also
For related functions such as dirname(), is_dir(), mkdir(), and rmdir(), see the Filesystem section.
chdir
(PHP 4, PHP 5, PHP 7)
chdir — Change directory
Description
$directory
) : bool
Changes PHP's current directory to
directory.
Parameters
-
directory -
The new current directory
Return Values
Returns TRUE on success or FALSE on failure.
Errors/Exceptions
Throws an error of level E_WARNING on failure.
Examples
Example #1 chdir() example
<?php
// current directory
echo getcwd() . "\n";
chdir('public_html');
// current directory
echo getcwd() . "\n";
?>
The above example will output something similar to:
/home/vincent /home/vincent/public_html
Notes
Note: When safe mode is enabled, PHP checks whether the directory in which the script is operating has the same UID (owner) as the script that is being executed.
If the PHP interpreter has been built with ZTS (Zend Thread Safety) enabled,
any changes to the current directory made through chdir()
will be invisible to the operating system. All built-in PHP functions will
still respect the change in current directory; but external library
functions called using FFI will not. You
can tell whether your copy of PHP was built with ZTS enabled using
php -i or the built-in constant
PHP_ZTS.
chroot
(PHP 4 >= 4.0.5, PHP 5, PHP 7)
chroot — Change the root directory
Description
$directory
) : bool
Changes the root directory of the current process to
directory, and changes the current
working directory to "/".
This function is only available to GNU and BSD systems, and only when using the CLI, CGI or Embed SAPI. Also, this function requires root privileges.
Parameters
-
directory -
The path to change the root directory to.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 chroot() example
<?php
chroot("/path/to/your/chroot/");
echo getcwd();
?>
The above example will output:
/
Notes
Note: This function is not implemented on Windows platforms.
Note: This function is not available in PHP interpreters built with ZTS (Zend Thread Safety) enabled. To check whether your copy of PHP was built with ZTS enabled, use php -i or test the built-in constant
PHP_ZTS.
closedir
(PHP 4, PHP 5, PHP 7)
closedir — Close directory handle
Description
$dir_handle
] ) : void
Closes the directory stream indicated by
dir_handle. The stream must have previously
been opened by opendir().
Parameters
Examples
Example #1 closedir() example
<?php
$dir = "/etc/php5/";
// Open a known directory, read directory into variable and then close
if (is_dir($dir)) {
if ($dh = opendir($dir)) {
$directory = readdir($dh);
closedir($dh);
}
}
?>
dir
(PHP 4, PHP 5, PHP 7)
dir — Return an instance of the Directory class
Description
A pseudo-object oriented mechanism for reading a directory. The
given directory is opened.
Parameters
-
directory -
Directory to open
-
context -
Note: Context support was added with PHP 5.0.0. For a description of
contexts, refer to Streams.
Return Values
Returns an instance of Directory, or NULL with
wrong parameters, or FALSE in case of another error.
Examples
Example #1 dir() example
Please note the fashion in which Directory::read()'s
return value is checked in the example below. We are explicitly
testing whether the return value is identical to (equal to and of
the same type as - see
Comparison Operators for more information) FALSE since
otherwise, any directory entry whose name evaluates to FALSE will
stop the loop.
<?php
$d = dir("/etc/php5");
echo "Handle: " . $d->handle . "\n";
echo "Path: " . $d->path . "\n";
while (false !== ($entry = $d->read())) {
echo $entry."\n";
}
$d->close();
?>
The above example will output something similar to:
Handle: Resource id #2 Path: /etc/php5 . .. apache cgi cli
Notes
Note:
The order in which directory entries are returned by the read method is system-dependent.
getcwd
(PHP 4, PHP 5, PHP 7)
getcwd — Gets the current working directory
Description
Gets the current working directory.
Return Values
Returns the current working directory on success, or FALSE on
failure.
On some Unix variants, getcwd() will return
FALSE if any one of the parent directories does not have the
readable or search mode set, even if the current directory
does. See chmod() for more information on
modes and permissions.
If the PHP interpreter has been built with ZTS (Zend Thread Safety) enabled, the current working directory returned by getcwd() may be different from that returned by operating system interfaces. External libraries (invoked through FFI) which depend on the current working directory will be affected.
Examples
Example #1 getcwd() example
<?php
// current directory
echo getcwd() . "\n";
chdir('cvs');
// current directory
echo getcwd() . "\n";
?>
The above example will output something similar to:
/home/didou /home/didou/cvs
opendir
(PHP 4, PHP 5, PHP 7)
opendir — Open directory handle
Description
$path
[, resource $context
] ) : resourceOpens up a directory handle to be used in subsequent closedir(), readdir(), and rewinddir() calls.
Parameters
-
path -
The directory path that is to be opened
-
context -
For a description of the
contextparameter, refer to the streams section of the manual.
Return Values
Returns a directory handle resource on success,
or FALSE on failure
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
This may happen if path is not a valid directory,
the directory can not be opened due to permission restrictions,
or due to filesystem errors.
Examples
Example #1 opendir() example
<?php
$dir = "/etc/php5/";
// Open a known directory, and proceed to read its contents
if (is_dir($dir)) {
if ($dh = opendir($dir)) {
while (($file = readdir($dh)) !== false) {
echo "filename: $file : filetype: " . filetype($dir . $file) . "\n";
}
closedir($dh);
}
}
?>
The above example will output something similar to:
filename: . : filetype: dir filename: .. : filetype: dir filename: apache : filetype: dir filename: cgi : filetype: dir filename: cli : filetype: dir
readdir
(PHP 4, PHP 5, PHP 7)
readdir — Read entry from directory handle
Description
$dir_handle
] ) : stringReturns the name of the next entry in the directory. The entries are returned in the order in which they are stored by the filesystem.
Parameters
Return Values
Returns the entry name on success or FALSE on failure.
This function may
return Boolean FALSE, but may also return a non-Boolean value which
evaluates to FALSE. Please read the section on Booleans for more
information. Use the ===
operator for testing the return value of this
function.
Examples
Example #1 List all entries in a directory
Please note the fashion in which readdir()'s
return value is checked in the examples below. We are explicitly
testing whether the return value is identical to (equal to and of
the same type as--see Comparison
Operators for more information) FALSE since otherwise,
any directory entry whose name evaluates to FALSE will stop the
loop (e.g. a directory named "0").
<?php
if ($handle = opendir('/path/to/files')) {
echo "Directory handle: $handle\n";
echo "Entries:\n";
/* This is the correct way to loop over the directory. */
while (false !== ($entry = readdir($handle))) {
echo "$entry\n";
}
/* This is the WRONG way to loop over the directory. */
while ($entry = readdir($handle)) {
echo "$entry\n";
}
closedir($handle);
}
?>
Example #2
List all entries in the current directory and strip out .
and ..
<?php
if ($handle = opendir('.')) {
while (false !== ($entry = readdir($handle))) {
if ($entry != "." && $entry != "..") {
echo "$entry\n";
}
}
closedir($handle);
}
?>
rewinddir
(PHP 4, PHP 5, PHP 7)
rewinddir — Rewind directory handle
Description
$dir_handle
] ) : void
Resets the directory stream indicated by
dir_handle to the beginning of the
directory.
Parameters
Return Values
Returns NULL on success or FALSE on failure.
scandir
(PHP 5, PHP 7)
scandir — List files and directories inside the specified path
Description
$directory
[, int $sorting_order = SCANDIR_SORT_ASCENDING
[, resource $context
]] ) : array
Returns an array of files and directories from the
directory.
Parameters
-
directory -
The directory that will be scanned.
-
sorting_order -
By default, the sorted order is alphabetical in ascending order. If the optional
sorting_orderis set toSCANDIR_SORT_DESCENDING, then the sort order is alphabetical in descending order. If it is set toSCANDIR_SORT_NONEthen the result is unsorted. -
context -
For a description of the
contextparameter, refer to the streams section of the manual.
Return Values
Returns an array of filenames on success, or FALSE on
failure. If directory is not a directory, then
boolean FALSE is returned, and an error of level
E_WARNING is generated.
Changelog
| Version | Description |
|---|---|
| 5.4.0 |
sorting_order constants
were added. Any nonzero value caused descending order in previous versions. So
for all PHP versions, use 0 for ascending order, and 1
for descending order. An option for SCANDIR_SORT_NONE behavior did not
exist prior to PHP 5.4.0.
|
Examples
Example #1 A simple scandir() example
<?php
$dir = '/tmp';
$files1 = scandir($dir);
$files2 = scandir($dir, 1);
print_r($files1);
print_r($files2);
?>
The above example will output something similar to:
Array
(
[0] => .
[1] => ..
[2] => bar.php
[3] => foo.txt
[4] => somedir
)
Array
(
[0] => somedir
[1] => foo.txt
[2] => bar.php
[3] => ..
[4] => .
)
Notes
A URL can be used as a filename with this function if the fopen wrappers have been enabled. See fopen() for more details on how to specify the filename. See the Supported Protocols and Wrappers for links to information about what abilities the various wrappers have, notes on their usage, and information on any predefined variables they may provide.
Table of Contents
- chdir — Change directory
- chroot — Change the root directory
- closedir — Close directory handle
- dir — Return an instance of the Directory class
- getcwd — Gets the current working directory
- opendir — Open directory handle
- readdir — Read entry from directory handle
- rewinddir — Rewind directory handle
- scandir — List files and directories inside the specified path
- Installing/Configuring
- Predefined Constants
- Directory — The Directory class
- Directory::close — Close directory handle
- Directory::read — Read entry from directory handle
- Directory::rewind — Rewind directory handle
- Directory Functions
- chdir — Change directory
- chroot — Change the root directory
- closedir — Close directory handle
- dir — Return an instance of the Directory class
- getcwd — Gets the current working directory
- opendir — Open directory handle
- readdir — Read entry from directory handle
- rewinddir — Rewind directory handle
- scandir — List files and directories inside the specified path
File Information
Introduction
The functions in this module try to guess the content type and encoding of a file by looking for certain magic byte sequences at specific positions within the file. While this is not a bullet proof approach the heuristics used do a very good job.
Installing/Configuring
Table of Contents
Requirements
Before PHP 5.3.0, the magic_open library is needed to build
this extension.
Installation
This extension is enabled by default as of PHP 5.3.0. Before this time, fileinfo was a PECL extension but is no longer maintained there. However, versions prior to 5.3+ may use the » discontinued PECL extension.
Windows users must include the bundled php_fileinfo.dll DLL file in php.ini to enable this extension.
The libmagic library is bundled with PHP, but includes PHP specific changes. A patch against libmagic named libmagic.patch is maintained and may be found within the PHP fileinfo extensions source.
| PHP Version | Updated libmagic Version | Notes |
|---|---|---|
| 5.3.2 | 5.03 | |
| 5.3.0 | 5.02 |
Runtime Configuration
This extension has no configuration directives defined in php.ini.
Resource Types
There is one resource used in Fileinfo extension: a magic database descriptor returned by finfo_open().
Predefined Constants
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
-
FILEINFO_NONE(integer) - No special handling.
-
FILEINFO_SYMLINK(integer) - Follow symlinks.
-
FILEINFO_MIME_TYPE(integer) - Return the mime type. Available since PHP 5.3.0.
-
FILEINFO_MIME_ENCODING(integer) - Return the mime encoding of the file. Available since PHP 5.3.0.
-
FILEINFO_MIME(integer) - Return the mime type and mime encoding as defined by RFC 2045.
-
FILEINFO_COMPRESS(integer) - Decompress compressed files. Disabled since PHP 5.3.0 due to thread safety issues.
-
FILEINFO_DEVICES(integer) - Look at the contents of blocks or character special devices.
-
FILEINFO_CONTINUE(integer) - Return all matches, not just the first.
-
FILEINFO_PRESERVE_ATIME(integer) - If possible preserve the original access time.
-
FILEINFO_RAW(integer) -
Don't translate unprintable characters to a
\ooooctal representation. -
FILEINFO_EXTENSION(integer) -
Returns the file extension appropriate for the MIME type detected in
the file.
For types that commonly have multiple file extensions, such as
JPEGimages, then the return value is multiple extensions separated by a forward slash e.g.:"jpeg/jpg/jpe/jfif". For unknown types not available in the magic.mime database, then return value is"???". Available since PHP 7.2.0.
Fileinfo Functions
finfo_buffer
finfo::buffer
(PHP 5 >= 5.3.0, PHP 7, PECL fileinfo >= 0.1.0)
finfo_buffer -- finfo::buffer — Return information about a string buffer
Description
Procedural style
$finfo
, string $string
[, int $options = FILEINFO_NONE
[, resource $context
]] ) : stringObject oriented style
$string
[, int $options = FILEINFO_NONE
[, resource $context
]] ) : stringThis function is used to get information about binary data in a string.
Parameters
-
finfo -
Fileinfo resource returned by finfo_open().
-
string -
Content of a file to be checked.
-
options -
One or disjunction of more Fileinfo constants.
-
context -
Return Values
Returns a textual description of the string
argument, or FALSE if an error occurred.
Examples
Example #1 A finfo_buffer() example
<?php
$finfo = new finfo(FILEINFO_MIME);
echo $finfo->buffer($_POST["script"]) . "\n";
?>
The above example will output something similar to:
application/x-sh; charset=us-ascii
finfo_close
(PHP >= 5.3.0, PECL fileinfo >= 0.1.0)
finfo_close — Close fileinfo resource
Description
$finfo
) : boolThis function closes the resource opened by finfo_open().
Return Values
Returns TRUE on success or FALSE on failure.
finfo_file
finfo::file
(PHP >= 5.3.0, PECL fileinfo >= 0.1.0)
finfo_file -- finfo::file — Return information about a file
Description
Procedural style
$finfo
, string $file_name
[, int $options = FILEINFO_NONE
[, resource $context
]] ) : stringObject oriented style
$file_name
[, int $options = FILEINFO_NONE
[, resource $context
]] ) : stringThis function is used to get information about a file.
Parameters
-
finfo -
Fileinfo resource returned by finfo_open().
-
file_name -
Name of a file to be checked.
-
options -
One or disjunction of more Fileinfo constants.
-
context -
For a description of
contexts, refer to Stream Functions.
Return Values
Returns a textual description of the contents of the
file_name argument, or FALSE if an error occurred.
Examples
Example #1 A finfo_file() example
<?php
$finfo = finfo_open(FILEINFO_MIME_TYPE); // return mime type ala mimetype extension
foreach (glob("*") as $filename) {
echo finfo_file($finfo, $filename) . "\n";
}
finfo_close($finfo);
?>
The above example will output something similar to:
text/html image/gif application/vnd.ms-excel
finfo_open
finfo::__construct
(PHP >= 5.3.0, PECL fileinfo >= 0.1.0)
finfo_open -- finfo::__construct — Create a new fileinfo resource
Description
Procedural style
$options = FILEINFO_NONE
[, string $magic_file = ""
]] ) : resourceObject oriented style (constructor):
This function opens a magic database and returns its resource.
Parameters
-
options -
One or disjunction of more Fileinfo constants.
-
magic_file -
Name of a magic database file, usually something like /path/to/magic.mime. If not specified, the
MAGICenvironment variable is used. If the environment variable isn't set, then PHP's bundled magic database will be used.Passing
NULLor an empty string will be equivalent to the default value.
Return Values
(Procedural style only)
Returns a magic database resource on success or FALSE on failure.
Notes
The expected magic database format changed in PHP 5.3.11 and 5.4.1. Due to this, the internal magic database was upgraded. This mostly effects code where an external magic database is used: reading an older magic file will now fail. Also, some textual representations of the mime types has changed, for instance for PHP would be "PHP script, ASCII text" instead of "PHP script text" returned.
Note:
Generally, using the bundled magic database (by leaving
magic_fileand theMAGICenvironment variables unset) is the best course of action unless you specifically need a custom magic database.
Examples
Example #1 Object oriented style
<?php
$finfo = new finfo(FILEINFO_MIME, "/usr/share/misc/magic"); // return mime type ala mimetype extension
/* get mime-type for a specific file */
$filename = "/usr/local/something.txt";
echo $finfo->file($filename);
?>
Example #2 Procedural style
<?php
$finfo = finfo_open(FILEINFO_MIME, "/usr/share/misc/magic"); // return mime type ala mimetype extension
if (!$finfo) {
echo "Opening fileinfo database failed";
exit();
}
/* get mime-type for a specific file */
$filename = "/usr/local/something.txt";
echo finfo_file($finfo, $filename);
/* close connection */
finfo_close($finfo);
?>
The above example will output:
text/plain; charset=us-ascii
finfo_set_flags
finfo::set_flags
(PHP >= 5.3.0, PECL fileinfo >= 0.1.0)
finfo_set_flags -- finfo::set_flags — Set libmagic configuration options
Description
Procedural style
Object oriented style
This function sets various Fileinfo options. Options can be set also directly in finfo_open() or other Fileinfo functions.
Parameters
-
finfo -
Fileinfo resource returned by finfo_open().
-
options -
One or disjunction of more Fileinfo constants.
Return Values
Returns TRUE on success or FALSE on failure.
mime_content_type
(PHP 4 >= 4.3.0, PHP 5, PHP 7)
mime_content_type — Detect MIME Content-type for a file
Description
$filename
) : stringReturns the MIME content type for a file as determined by using information from the magic.mime file.
Parameters
-
filename -
Path to the tested file.
Return Values
Returns the content type in MIME format, like
text/plain or application/octet-stream,
or FALSE on failure.
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Examples
Example #1 mime_content_type() Example
<?php
echo mime_content_type('php.gif') . "\n";
echo mime_content_type('test.php');
?>
The above example will output:
image/gif text/plain
Table of Contents
- finfo_buffer — Return information about a string buffer
- finfo_close — Close fileinfo resource
- finfo_file — Return information about a file
- finfo_open — Create a new fileinfo resource
- finfo_set_flags — Set libmagic configuration options
- mime_content_type — Detect MIME Content-type for a file
The finfo class
(PHP 5 >= 5.3.0, PHP 7, PECL fileinfo >= 0.1.0)
Introduction
This class provides an object oriented interface into the fileinfo functions.
Class synopsis
finfo::buffer
(PHP 5 >= 5.3.0, PHP 7, PECL fileinfo >= 0.1.0)
finfo::buffer — Alias of finfo_buffer()
Description
$string
[, int $options = FILEINFO_NONE
[, resource $context
]] ) : stringThis function is an alias of: finfo_buffer()
Description
$options = FILEINFO_NONE
[, string $magic_file = ""
]] )This function is an alias of: finfo_open()
Description
$file_name
[, int $options = FILEINFO_NONE
[, resource $context
]] ) : stringThis function is an alias of: finfo_file()
finfo::set_flags
(PHP >= 5.3.0, PECL fileinfo >= 0.1.0)
finfo::set_flags — Alias of finfo_set_flags()
Description
$options
) : boolThis function is an alias of: finfo_set_flags()
Table of Contents
- finfo::buffer — Alias of finfo_buffer()
- finfo::__construct — Alias of finfo_open
- finfo::file — Alias of finfo_file()
- finfo::set_flags — Alias of finfo_set_flags()
- Introduction
- Installing/Configuring
- Predefined Constants
- Fileinfo Functions
- finfo_buffer — Return information about a string buffer
- finfo_close — Close fileinfo resource
- finfo_file — Return information about a file
- finfo_open — Create a new fileinfo resource
- finfo_set_flags — Set libmagic configuration options
- mime_content_type — Detect MIME Content-type for a file
- finfo — The finfo class
- finfo::buffer — Alias of finfo_buffer()
- finfo::__construct — Alias of finfo_open
- finfo::file — Alias of finfo_file()
- finfo::set_flags — Alias of finfo_set_flags()
Filesystem
Introduction
No external libraries are needed to build this extension, but if you want
PHP to support LFS (large files) on Linux, then you need to have a recent
glibc and you need compile PHP with the following compiler flags:
-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64.
Installing/Configuring
Table of Contents
Requirements
No external libraries are needed to build this extension.
Installation
There is no installation needed to use these functions; they are part of the PHP core.
Runtime Configuration
The behaviour of these functions is affected by settings in php.ini.
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| allow_url_fopen | "1" | PHP_INI_SYSTEM | |
| allow_url_include | "0" | PHP_INI_SYSTEM | Available since PHP 5.2.0. Deprecated as of PHP 7.4.0. |
| user_agent | NULL | PHP_INI_ALL | |
| default_socket_timeout | "60" | PHP_INI_ALL | |
| from | "" | PHP_INI_ALL | |
| auto_detect_line_endings | "0" | PHP_INI_ALL | |
| sys_temp_dir | "" | PHP_INI_SYSTEM | Available since PHP 5.5.0. |
Here's a short explanation of the configuration directives.
-
allow_url_fopenboolean -
This option enables the URL-aware fopen wrappers that enable accessing URL object like files. Default wrappers are provided for the access of remote files using the ftp or http protocol, some extensions like zlib may register additional wrappers.
-
allow_url_includeboolean -
This option allows the use of URL-aware fopen wrappers with the following functions: include, include_once, require, require_once.
Note:
This setting requires allow_url_fopen to be on.
-
user_agentstring -
Define the user agent for PHP to send.
-
default_socket_timeoutinteger -
Default timeout (in seconds) for socket based streams. Specifying a negative value means an infinite timeout.
-
fromstring -
The email address to be used on unauthenticated FTP connections and as the value of From header for HTTP connections, when using the ftp and http wrappers, respectively.
-
auto_detect_line_endingsboolean -
When turned on, PHP will examine the data read by fgets() and file() to see if it is using Unix, MS-Dos or Macintosh line-ending conventions.
This enables PHP to interoperate with Macintosh systems, but defaults to Off, as there is a very small performance penalty when detecting the EOL conventions for the first line, and also because people using carriage-returns as item separators under Unix systems would experience non-backwards-compatible behaviour.
-
sys_temp_dirstring -
Resource Types
The file system uses streams as their resource type. Streams
are documented in its own reference chapter, Streams.
Predefined Constants
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
-
SEEK_SET(integer) -
SEEK_CUR(integer) -
SEEK_END(integer) -
LOCK_SH(integer) -
LOCK_EX(integer) -
LOCK_UN(integer) -
LOCK_NB(integer) -
GLOB_BRACE(integer) -
GLOB_ONLYDIR(integer) -
GLOB_MARK(integer) -
GLOB_NOSORT(integer) -
GLOB_NOCHECK(integer) -
GLOB_NOESCAPE(integer) -
GLOB_AVAILABLE_FLAGS(integer) -
PATHINFO_DIRNAME(integer) -
PATHINFO_BASENAME(integer) -
PATHINFO_EXTENSION(integer) -
PATHINFO_FILENAME(integer) - Since PHP 5.2.0.
-
FILE_USE_INCLUDE_PATH(integer) -
Search for
filenamein include_path. -
FILE_NO_DEFAULT_CONTEXT(integer) -
FILE_APPEND(integer) - Append content to existing file.
-
FILE_IGNORE_NEW_LINES(integer) - Strip EOL characters.
-
FILE_SKIP_EMPTY_LINES(integer) - Skip empty lines.
-
FILE_BINARY(integer) -
Binary mode (since PHP 5.2.7).
Note:
This constant has no effect, and is only available for
forward compatibility. -
FILE_TEXT(integer) -
Text mode (since PHP 5.2.7).
Note:
This constant has no effect, and is only available for
forward compatibility. -
INI_SCANNER_NORMAL(integer) - Normal INI scanner mode (since PHP 5.3).
-
INI_SCANNER_RAW(integer) - Raw INI scanner mode (since PHP 5.3).
-
INI_SCANNER_TYPED(integer) - Typed INI scanner mode (since PHP 5.6.1).
-
FNM_NOESCAPE(integer) - Disable backslash escaping.
-
FNM_PATHNAME(integer) - Slash in string only matches slash in the given pattern.
-
FNM_PERIOD(integer) - Leading period in string must be exactly matched by period in the given pattern.
-
FNM_CASEFOLD(integer) - Caseless match. Part of the GNU extension.
Filesystem Functions
See Also
For related functions, see also the Directory and Program Execution sections.
For a list and explanation of the various URL wrappers that can be used as remote files, see also Supported Protocols and Wrappers.
basename
(PHP 4, PHP 5, PHP 7)
basename — Returns trailing name component of path
Description
$path
[, string $suffix
] ) : stringGiven a string containing the path to a file or directory, this function will return the trailing name component.
Note:
basename() operates naively on the input string, and is not aware of the actual filesystem, or path components such as "
..".
basename() is locale aware, so for it to see the correct basename with multibyte character paths, the matching locale must be set using the setlocale() function.
Parameters
-
path -
A path.
On Windows, both slash (
/) and backslash (\) are used as directory separator character. In other environments, it is the forward slash (/). -
suffix -
If the name component ends in
suffixthis will also be cut off.
Return Values
Returns the base name of the given path.
Examples
Example #1 basename() example
<?php
echo "1) ".basename("/etc/sudoers.d", ".d").PHP_EOL;
echo "2) ".basename("/etc/sudoers.d").PHP_EOL;
echo "3) ".basename("/etc/passwd").PHP_EOL;
echo "4) ".basename("/etc/").PHP_EOL;
echo "5) ".basename(".").PHP_EOL;
echo "6) ".basename("/");
?>
The above example will output:
1) sudoers 2) sudoers.d 3) passwd 4) etc 5) . 6)
See Also
- dirname() - Returns a parent directory's path
- pathinfo() - Returns information about a file path
chgrp
(PHP 4, PHP 5, PHP 7)
chgrp — Changes file group
Description
Attempts to change the group of the file filename
to group.
Only the superuser may change the group of a file arbitrarily; other users may change the group of a file to any group of which that user is a member.
Parameters
-
filename -
Path to the file.
-
group -
A group name or number.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 Changing a file's group
<?php
$filename = 'shared_file.txt';
$format = "%s's Group ID @ %s: %d\n";
printf($format, $filename, date('r'), filegroup($filename));
chgrp($filename, 8);
clearstatcache(); // do not cache filegroup() results
printf($format, $filename, date('r'), filegroup($filename));
?>
Notes
Note: This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.
Note: When safe mode is enabled, PHP checks whether the files or directories being operated upon have the same UID (owner) as the script that is being executed.
Note: On Windows, this function fails silently when applied on a regular file.
chmod
(PHP 4, PHP 5, PHP 7)
chmod — Changes file mode
Description
$filename
, int $mode
) : bool
Attempts to change the mode of the specified file to that given in
mode.
Parameters
-
filename -
Path to the file.
-
mode -
Note that
modeis not automatically assumed to be an octal value, so to ensure the expected operation, you need to prefixmodewith a zero (0). Strings such as "g+w" will not work properly.<?php
chmod("/somedir/somefile", 755); // decimal; probably incorrect
chmod("/somedir/somefile", "u+rwx,go+rx"); // string; incorrect
chmod("/somedir/somefile", 0755); // octal; correct value of mode
?>The
modeparameter consists of three octal number components specifying access restrictions for the owner, the user group in which the owner is in, and to everybody else in this order. One component can be computed by adding up the needed permissions for that target user base. Number 1 means that you grant execute rights, number 2 means that you make the file writeable, number 4 means that you make the file readable. Add up these numbers to specify needed rights. You can also read more about modes on Unix systems with 'man 1 chmod' and 'man 2 chmod'.<?php
// Read and write for owner, nothing for everybody else
chmod("/somedir/somefile", 0600);
// Read and write for owner, read for everybody else
chmod("/somedir/somefile", 0644);
// Everything for owner, read and execute for others
chmod("/somedir/somefile", 0755);
// Everything for owner, read and execute for owner's group
chmod("/somedir/somefile", 0750);
?>
Return Values
Returns TRUE on success or FALSE on failure.
Notes
Note:
The current user is the user under which PHP runs. It is probably not the same user you use for normal shell or FTP access. The mode can be changed only by user who owns the file on most systems.
Note: This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.
Note:
When safe mode is enabled, PHP checks whether the files or directories you are about to operate on have the same UID (owner) as the script that is being executed. In addition, you cannot set the SUID, SGID and sticky bits.
See Also
- chown() - Changes file owner
- chgrp() - Changes file group
- fileperms() - Gets file permissions
- stat() - Gives information about a file
chown
(PHP 4, PHP 5, PHP 7)
chown — Changes file owner
Description
Attempts to change the owner of the file filename
to user user. Only the superuser may change the
owner of a file.
Parameters
-
filename -
Path to the file.
-
user -
A user name or number.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 Simple chown() usage
<?php
// File name and username to use
$file_name= "foo.php";
$path = "/home/sites/php.net/public_html/sandbox/" . $file_name ;
$user_name = "root";
// Set the user
chown($path, $user_name);
// Check the result
$stat = stat($path);
print_r(posix_getpwuid($stat['uid']));
?>
The above example will output something similar to:
Array
(
[name] => root
[passwd] => x
[uid] => 0
[gid] => 0
[gecos] => root
[dir] => /root
[shell] => /bin/bash
)
Notes
Note: This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.
Note: When safe mode is enabled, PHP checks whether the files or directories being operated upon have the same UID (owner) as the script that is being executed.
Note: On Windows, this function fails silently when applied on a regular file.
clearstatcache
(PHP 4, PHP 5, PHP 7)
clearstatcache — Clears file status cache
Description
$clear_realpath_cache = FALSE
[, string $filename
]] ) : voidWhen you use stat(), lstat(), or any of the other functions listed in the affected functions list (below), PHP caches the information those functions return in order to provide faster performance. However, in certain cases, you may want to clear the cached information. For instance, if the same file is being checked multiple times within a single script, and that file is in danger of being removed or changed during that script's operation, you may elect to clear the status cache. In these cases, you can use the clearstatcache() function to clear the information that PHP caches about a file.
You should also note that PHP doesn't cache information about non-existent
files. So, if you call file_exists() on a file that
doesn't exist, it will return FALSE until you create the file. If you
create the file, it will return TRUE even if you then delete the file.
However unlink() clears the cache automatically.
Note:
This function caches information about specific filenames, so you only need to call clearstatcache() if you are performing multiple operations on the same filename and require the information about that particular file to not be cached.
Affected functions include stat(), lstat(), file_exists(), is_writable(), is_readable(), is_executable(), is_file(), is_dir(), is_link(), filectime(), fileatime(), filemtime(), fileinode(), filegroup(), fileowner(), filesize(), filetype(), and fileperms().
Parameters
-
clear_realpath_cache -
Whether to clear the realpath cache or not.
-
filename -
Clear the realpath and the stat cache for a specific filename only; only used if
clear_realpath_cacheisTRUE.
Return Values
No value is returned.
Changelog
| Version | Description |
|---|---|
| 5.3.0 |
Added optional clear_realpath_cache
and filename parameters.
|
Examples
Example #1 clearstatcache() example
<?php
$file = 'output_log.txt';
function get_owner($file)
{
$stat = stat($file);
$user = posix_getpwuid($stat['uid']);
return $user['name'];
}
$format = "UID @ %s: %s\n";
printf($format, date('r'), get_owner($file));
chown($file, 'ross');
printf($format, date('r'), get_owner($file));
clearstatcache();
printf($format, date('r'), get_owner($file));
?>
The above example will output something similar to:
UID @ Sun, 12 Oct 2008 20:48:28 +0100: root UID @ Sun, 12 Oct 2008 20:48:28 +0100: root UID @ Sun, 12 Oct 2008 20:48:28 +0100: ross
copy
(PHP 4, PHP 5, PHP 7)
copy — Copies file
Description
$source
, string $dest
[, resource $context
] ) : bool
Makes a copy of the file source to
dest.
If you wish to move a file, use the rename() function.
Parameters
-
source -
Path to the source file.
-
dest -
The destination path. If
destis a URL, the copy operation may fail if the wrapper does not support overwriting of existing files.WarningIf the destination file already exists, it will be overwritten.
-
context -
A valid context resource created with stream_context_create().
Return Values
Returns TRUE on success or FALSE on failure.
Changelog
| Version | Description |
|---|---|
| 5.3.4 |
Changed the context parameter to actually have an effect.
Previously, any context was ignored.
|
| 5.3.0 | Added context support. |
Examples
Example #1 copy() example
<?php
$file = 'example.txt';
$newfile = 'example.txt.bak';
if (!copy($file, $newfile)) {
echo "failed to copy $file...\n";
}
?>
See Also
- move_uploaded_file() - Moves an uploaded file to a new location
- rename() - Renames a file or directory
- The section of the manual about handling file uploads
dirname
(PHP 4, PHP 5, PHP 7)
dirname — Returns a parent directory's path
Description
$path
[, int $levels = 1
] ) : string
Given a string containing the path of a file or directory, this function
will return the parent directory's path that is
levels up from the current directory.
Note:
dirname() operates naively on the input string, and is not aware of the actual filesystem, or path components such as "
..".
dirname() is locale aware, so for it to see the correct directory name with multibyte character paths, the matching locale must be set using the setlocale() function.
Parameters
-
path -
A path.
On Windows, both slash (
/) and backslash (\) are used as directory separator character. In other environments, it is the forward slash (/). -
levels -
The number of parent directories to go up.
This must be an integer greater than 0.
Return Values
Returns the path of a parent directory. If there are no slashes in
path, a dot ('.') is returned,
indicating the current directory. Otherwise, the returned string is
path with any trailing
/component removed.
Changelog
| Version | Description |
|---|---|
| 7.0.0 |
Added the optional levels parameter.
|
Examples
Example #1 dirname() example
<?php
echo dirname("/etc/passwd") . PHP_EOL;
echo dirname("/etc/") . PHP_EOL;
echo dirname(".") . PHP_EOL;
echo dirname("C:\\") . PHP_EOL;
echo dirname("/usr/local/lib", 2);
The above example will output something similar to:
/etc / (or \ on Windows) . C:\ /usr
See Also
- basename() - Returns trailing name component of path
- pathinfo() - Returns information about a file path
- realpath() - Returns canonicalized absolute pathname
disk_free_space
(PHP 4 >= 4.1.0, PHP 5, PHP 7)
disk_free_space — Returns available space on filesystem or disk partition
Description
$directory
) : floatGiven a string containing a directory, this function will return the number of bytes available on the corresponding filesystem or disk partition.
Parameters
-
directory -
A directory of the filesystem or disk partition.
Note:
Given a file name instead of a directory, the behaviour of the function is unspecified and may differ between operating systems and PHP versions.
Return Values
Returns the number of available bytes as a float
or FALSE on failure.
Examples
Example #1 disk_free_space() example
<?php
// $df contains the number of bytes available on "/"
$df = disk_free_space("/");
// On Windows:
$df_c = disk_free_space("C:");
$df_d = disk_free_space("D:");
?>
Notes
Note: This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.
disk_total_space
(PHP 4 >= 4.1.0, PHP 5, PHP 7)
disk_total_space — Returns the total size of a filesystem or disk partition
Description
$directory
) : floatGiven a string containing a directory, this function will return the total number of bytes on the corresponding filesystem or disk partition.
Parameters
-
directory -
A directory of the filesystem or disk partition.
Return Values
Returns the total number of bytes as a float
or FALSE on failure.
Examples
Example #1 disk_total_space() example
<?php
// $ds contains the total number of bytes available on "/"
$ds = disk_total_space("/");
// On Windows:
$ds = disk_total_space("C:");
$ds = disk_total_space("D:");
?>
Notes
Note: This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.
Description
This function is an alias of: disk_free_space().
fclose
(PHP 4, PHP 5, PHP 7)
fclose — Closes an open file pointer
Description
$handle
) : bool
The file pointed to by handle is closed.
Parameters
-
handle -
The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen().
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 A simple fclose() example
<?php
$handle = fopen('somefile.txt', 'r');
fclose($handle);
?>
feof
(PHP 4, PHP 5, PHP 7)
feof — Tests for end-of-file on a file pointer
Description
$handle
) : boolTests for end-of-file on a file pointer.
Parameters
-
handle -
The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen() (and not yet closed by fclose()).
Return Values
Returns TRUE if the file pointer is at EOF or an error occurs
(including socket timeout); otherwise returns FALSE.
Notes
If a connection opened by fsockopen() wasn't closed by the server, feof() will hang. To workaround this, see below example:
Example #1 Handling timeouts with feof()
<?php
function safe_feof($fp, &$start = NULL) {
$start = microtime(true);
return feof($fp);
}
/* Assuming $fp is previously opened by fsockopen() */
$start = NULL;
$timeout = ini_get('default_socket_timeout');
while(!safe_feof($fp, $start) && (microtime(true) - $start) < $timeout)
{
/* Handle */
}
?>
If the passed file pointer is not valid you may get an infinite loop, because
feof() fails to return TRUE.
Example #2 feof() example with an invalid file pointer
<?php
// if file can not be read or doesn't exist fopen function returns FALSE
$file = @fopen("no_such_file", "r");
// FALSE from fopen will issue warning and result in infinite loop here
while (!feof($file)) {
}
fclose($file);
?>
fflush
(PHP 4 >= 4.0.1, PHP 5, PHP 7)
fflush — Flushes the output to a file
Description
$handle
) : bool
This function forces a write of all buffered output to the resource
pointed to by the file handle.
Parameters
-
handle -
The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen() (and not yet closed by fclose()).
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 File write example using fflush()
<?php
$filename = 'bar.txt';
$file = fopen($filename, 'r+');
rewind($file);
fwrite($file, 'Foo');
fflush($file);
ftruncate($file, ftell($file));
fclose($file);
?>
fgetc
(PHP 4, PHP 5, PHP 7)
fgetc — Gets character from file pointer
Description
$handle
) : stringGets a character from the given file pointer.
Parameters
-
handle -
The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen() (and not yet closed by fclose()).
Return Values
Returns a string containing a single character read from the file pointed
to by handle. Returns FALSE on EOF.
This function may
return Boolean FALSE, but may also return a non-Boolean value which
evaluates to FALSE. Please read the section on Booleans for more
information. Use the ===
operator for testing the return value of this
function.
Examples
Example #1 A fgetc() example
<?php
$fp = fopen('somefile.txt', 'r');
if (!$fp) {
echo 'Could not open file somefile.txt';
}
while (false !== ($char = fgetc($fp))) {
echo "$char\n";
}
?>
Notes
Note: This function is binary-safe.
See Also
- fread() - Binary-safe file read
- fopen() - Opens file or URL
- popen() - Opens process file pointer
- fsockopen() - Open Internet or Unix domain socket connection
- fgets() - Gets line from file pointer
fgetcsv
(PHP 4, PHP 5, PHP 7)
fgetcsv — Gets line from file pointer and parse for CSV fields
Description
$handle
[, int $length = 0
[, string $delimiter = ","
[, string $enclosure = '"'
[, string $escape = "\\"
]]]] ) : arraySimilar to fgets() except that fgetcsv() parses the line it reads for fields in CSV format and returns an array containing the fields read.
Note:
The locale settings are taken into account by this function. If
LC_CTYPEis e.g.en_US.UTF-8, files in one-byte encodings may be read wrongly by this function.
Parameters
-
handle -
A valid file pointer to a file successfully opened by fopen(), popen(), or fsockopen().
-
length -
Must be greater than the longest line (in characters) to be found in the CSV file (allowing for trailing line-end characters). Otherwise the line is split in chunks of
lengthcharacters, unless the split would occur inside an enclosure.Omitting this parameter (or setting it to 0 in PHP 5.1.0 and later) the maximum line length is not limited, which is slightly slower.
-
delimiter -
The optional
delimiterparameter sets the field delimiter (one character only). -
enclosure -
The optional
enclosureparameter sets the field enclosure character (one character only). -
escape -
The optional
escapeparameter sets the escape character (at most one character). An empty string ("") disables the proprietary escape mechanism.Note: Usually an
enclosurecharacter is escaped inside a field by doubling it; however, theescapecharacter can be used as an alternative. So for the default parameter values""and\"have the same meaning. Other than allowing to escape theenclosurecharacter theescapecharacter has no special meaning; it isn't even meant to escape itself.
Return Values
Returns an indexed array containing the fields read.
Note:
A blank line in a CSV file will be returned as an array comprising a single null field, and will not be treated as an error.
Note: If PHP is not properly recognizing the line endings when reading files either on or created by a Macintosh computer, enabling the auto_detect_line_endings run-time configuration option may help resolve the problem.
fgetcsv() returns NULL if an invalid
handle is supplied or FALSE on other errors,
including end of file.
Changelog
| Version | Description |
|---|---|
| 7.4.0 |
The escape parameter now also accepts an empty
string to disable the proprietary escape mechanism.
|
| 5.3.0 |
The escape parameter was added
|
| 5.1.0 |
The length is now optional.
Default is 0, meaning no length limit.
|
Examples
Example #1 Read and print the entire contents of a CSV file
<?php
$row = 1;
if (($handle = fopen("test.csv", "r")) !== FALSE) {
while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
$num = count($data);
echo "<p> $num fields in line $row: <br /></p>\n";
$row++;
for ($c=0; $c < $num; $c++) {
echo $data[$c] . "<br />\n";
}
}
fclose($handle);
}
?>
See Also
- str_getcsv() - Parse a CSV string into an array
- explode() - Split a string by a string
- file() - Reads entire file into an array
- pack() - Pack data into binary string
- fputcsv() - Format line as CSV and write to file pointer
fgets
(PHP 4, PHP 5, PHP 7)
fgets — Gets line from file pointer
Description
$handle
[, int $length
] ) : stringGets a line from file pointer.
Parameters
-
handle -
The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen() (and not yet closed by fclose()).
-
length -
Reading ends when
length- 1 bytes have been read, or a newline (which is included in the return value), or an EOF (whichever comes first). If no length is specified, it will keep reading from the stream until it reaches the end of the line.
Return Values
Returns a string of up to length - 1 bytes read from
the file pointed to by handle. If there is no more data
to read in the file pointer, then FALSE is returned.
If an error occurs, FALSE is returned.
Examples
Example #1 Reading a file line by line
<?php
$handle = @fopen("/tmp/inputfile.txt", "r");
if ($handle) {
while (($buffer = fgets($handle, 4096)) !== false) {
echo $buffer;
}
if (!feof($handle)) {
echo "Error: unexpected fgets() fail\n";
}
fclose($handle);
}
?>
Notes
Note: If PHP is not properly recognizing the line endings when reading files either on or created by a Macintosh computer, enabling the auto_detect_line_endings run-time configuration option may help resolve the problem.
Note:
People used to the 'C' semantics of fgets() should note the difference in how
EOFis returned.
See Also
- fgetss() - Gets line from file pointer and strip HTML tags
- fread() - Binary-safe file read
- fgetc() - Gets character from file pointer
- stream_get_line() - Gets line from stream resource up to a given delimiter
- fopen() - Opens file or URL
- popen() - Opens process file pointer
- fsockopen() - Open Internet or Unix domain socket connection
- stream_set_timeout() - Set timeout period on a stream
fgetss
(PHP 4, PHP 5, PHP 7)
fgetss — Gets line from file pointer and strip HTML tags
This function has been DEPRECATED as of PHP 7.3.0. Relying on this function is highly discouraged.
Description
$handle
[, int $length
[, string $allowable_tags
]] ) : stringIdentical to fgets(), except that fgetss() attempts to strip any NUL bytes, HTML and PHP tags from the text it reads. The function retains the parsing state from call to call, and as such is not equivalent to calling strip_tags() on the return value of fgets().
Parameters
-
handle -
The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen() (and not yet closed by fclose()).
-
length -
Length of the data to be retrieved.
-
allowable_tags -
You can use the optional third parameter to specify tags which should not be stripped. See strip_tags() for details regarding
allowable_tags.
Return Values
Returns a string of up to length - 1 bytes read from
the file pointed to by handle, with all HTML and PHP
code stripped.
If an error occurs, returns FALSE.
Examples
Example #1 Reading a PHP file line-by-line
<?php
$str = <<<EOD
<html><body>
<p>Welcome! Today is the <?php echo(date('jS')); ?> of <?= date('F'); ?>.</p>
</body></html>
Text outside of the HTML block.
EOD;
file_put_contents('sample.php', $str);
$handle = @fopen("sample.php", "r");
if ($handle) {
while (!feof($handle)) {
$buffer = fgetss($handle, 4096);
echo $buffer;
}
fclose($handle);
}
?>
The above example will output something similar to:
Welcome! Today is the of .
Text outside of the HTML block.
Notes
Note: If PHP is not properly recognizing the line endings when reading files either on or created by a Macintosh computer, enabling the auto_detect_line_endings run-time configuration option may help resolve the problem.
See Also
- fgets() - Gets line from file pointer
- fopen() - Opens file or URL
- popen() - Opens process file pointer
- fsockopen() - Open Internet or Unix domain socket connection
- strip_tags() - Strip HTML and PHP tags from a string
- SplFileObject::fgetss() - Gets line from file and strip HTML tags
- The string.strip_tags filter
file_exists
(PHP 4, PHP 5, PHP 7)
file_exists — Checks whether a file or directory exists
Description
$filename
) : boolChecks whether a file or directory exists.
Parameters
-
filename -
Path to the file or directory.
On windows, use //computername/share/filename or \\computername\share\filename to check files on network shares.
Return Values
Returns TRUE if the file or directory specified by
filename exists; FALSE otherwise.
Note:
This function will return
FALSEfor symlinks pointing to non-existing files.
This function returns FALSE for files inaccessible due to safe mode restrictions. However these
files still can be included if
they are located in safe_mode_include_dir.
Note:
The check is done using the real UID/GID instead of the effective one.
Note: Because PHP's integer type is signed and many platforms use 32bit integers, some filesystem functions may return unexpected results for files which are larger than 2GB.
Examples
Example #1 Testing whether a file exists
<?php
$filename = '/path/to/foo.txt';
if (file_exists($filename)) {
echo "The file $filename exists";
} else {
echo "The file $filename does not exist";
}
?>
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
See Also
- is_readable() - Tells whether a file exists and is readable
- is_writable() - Tells whether the filename is writable
- is_file() - Tells whether the filename is a regular file
- file() - Reads entire file into an array
file_get_contents
(PHP 4 >= 4.3.0, PHP 5, PHP 7)
file_get_contents — Reads entire file into a string
Description
$filename
[, bool $use_include_path = FALSE
[, resource $context
[, int $offset = 0
[, int $maxlen
]]]] ) : string
This function is similar to file(), except that
file_get_contents() returns the file in a
string, starting at the specified offset
up to maxlen bytes. On failure,
file_get_contents() will return FALSE.
file_get_contents() is the preferred way to read the contents of a file into a string. It will use memory mapping techniques if supported by your OS to enhance performance.
Note:
If you're opening a URI with special characters, such as spaces, you need to encode the URI with urlencode().
Parameters
-
filename -
Name of the file to read.
-
use_include_path -
Note:
The
FILE_USE_INCLUDE_PATHconstant can be used to trigger include path search. This is not possible if strict typing is enabled, sinceFILE_USE_INCLUDE_PATHis an int. UseTRUEinstead. -
context -
A valid context resource created with stream_context_create(). If you don't need to use a custom context, you can skip this parameter by
NULL. -
offset -
The offset where the reading starts on the original stream. Negative offsets count from the end of the stream.
Seeking (
offset) is not supported with remote files. Attempting to seek on non-local files may work with small offsets, but this is unpredictable because it works on the buffered stream. -
maxlen -
Maximum length of data read. The default is to read until end of file is reached. Note that this parameter is applied to the stream processed by the filters.
Return Values
The function returns the read data or FALSE on failure.
This function may
return Boolean FALSE, but may also return a non-Boolean value which
evaluates to FALSE. Please read the section on Booleans for more
information. Use the ===
operator for testing the return value of this
function.
Errors/Exceptions
An E_WARNING level error is generated if filename cannot be found, maxlength
is less than zero, or if seeking to the specified offset in the stream fails.
Examples
Example #1 Get and output the source of the homepage of a website
<?php
$homepage = file_get_contents('http://www.example.com/');
echo $homepage;
?>
Example #2 Searching within the include_path
<?php
// If strict types are enabled i.e. declare(strict_types=1);
$file = file_get_contents('./people.txt', true);
// Otherwise
$file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);
?>
Example #3 Reading a section of a file
<?php
// Read 14 characters starting from the 21st character
$section = file_get_contents('./people.txt', FALSE, NULL, 20, 14);
var_dump($section);
?>
The above example will output something similar to:
string(14) "lle Bjori Ro"
Example #4 Using stream contexts
<?php
// Create a stream
$opts = array(
'http'=>array(
'method'=>"GET",
'header'=>"Accept-language: en\r\n" .
"Cookie: foo=bar\r\n"
)
);
$context = stream_context_create($opts);
// Open the file using the HTTP headers set above
$file = file_get_contents('http://www.example.com/', false, $context);
?>
Changelog
| Version | Description |
|---|---|
| 7.1.0 |
Support for negative offsets has been added.
|
| 5.1.0 |
Added the offset and
maxlen parameters.
|
Notes
Note: This function is binary-safe.
A URL can be used as a filename with this function if the fopen wrappers have been enabled. See fopen() for more details on how to specify the filename. See the Supported Protocols and Wrappers for links to information about what abilities the various wrappers have, notes on their usage, and information on any predefined variables they may provide.
When using SSL, Microsoft IIS
will violate the protocol by closing the connection without sending a
close_notify indicator. PHP will report this as "SSL: Fatal
Protocol Error" when you reach the end of the data. To work around this, the
value of error_reporting should be
lowered to a level that does not include warnings.
PHP can detect buggy IIS server software when you open
the stream using the https:// wrapper and will suppress the
warning. When using fsockopen() to create an
ssl:// socket, the developer is responsible for detecting
and suppressing this warning.
See Also
- file() - Reads entire file into an array
- fgets() - Gets line from file pointer
- fread() - Binary-safe file read
- readfile() - Outputs a file
- file_put_contents() - Write data to a file
- stream_get_contents() - Reads remainder of a stream into a string
- stream_context_create() - Creates a stream context
- $http_response_header
file_put_contents
(PHP 5, PHP 7)
file_put_contents — Write data to a file
Description
$filename
, mixed $data
[, int $flags = 0
[, resource $context
]] ) : intThis function is identical to calling fopen(), fwrite() and fclose() successively to write data to a file.
If filename does not exist, the file is created.
Otherwise, the existing file is overwritten, unless the
FILE_APPEND flag is set.
Parameters
-
filename -
Path to the file where to write the data.
-
data -
The data to write. Can be either a string, an array or a stream resource.
If
datais a stream resource, the remaining buffer of that stream will be copied to the specified file. This is similar with using stream_copy_to_stream().You can also specify the
dataparameter as a single dimension array. This is equivalent tofile_put_contents($filename, implode('', $array)). -
flags -
The value of
flagscan be any combination of the following flags, joined with the binary OR (|) operator.Available flags Flag Description FILE_USE_INCLUDE_PATHSearch for filenamein the include directory. See include_path for more information.FILE_APPENDIf file filenamealready exists, append the data to the file instead of overwriting it.LOCK_EXAcquire an exclusive lock on the file while proceeding to the writing. In other words, a flock() call happens between the fopen() call and the fwrite() call. This is not identical to an fopen() call with mode "x". -
context -
A valid context resource created with stream_context_create().
Return Values
This function returns the number of bytes that were written to the file, or
FALSE on failure.
This function may
return Boolean FALSE, but may also return a non-Boolean value which
evaluates to FALSE. Please read the section on Booleans for more
information. Use the ===
operator for testing the return value of this
function.
Examples
Example #1 Simple usage example
<?php
$file = 'people.txt';
// Open the file to get existing content
$current = file_get_contents($file);
// Append a new person to the file
$current .= "John Smith\n";
// Write the contents back to the file
file_put_contents($file, $current);
?>
Example #2 Using flags
<?php
$file = 'people.txt';
// The new person to add to the file
$person = "John Smith\n";
// Write the contents to the file,
// using the FILE_APPEND flag to append the content to the end of the file
// and the LOCK_EX flag to prevent anyone else writing to the file at the same time
file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
?>
Changelog
| Version | Description |
|---|---|
| 5.1.0 |
Added support for LOCK_EX and the ability to pass
a stream resource to the data parameter
|
Notes
Note: This function is binary-safe.
A URL can be used as a filename with this function if the fopen wrappers have been enabled. See fopen() for more details on how to specify the filename. See the Supported Protocols and Wrappers for links to information about what abilities the various wrappers have, notes on their usage, and information on any predefined variables they may provide.
See Also
- fopen() - Opens file or URL
- fwrite() - Binary-safe file write
- file_get_contents() - Reads entire file into a string
- stream_context_create() - Creates a stream context
file
(PHP 4, PHP 5, PHP 7)
file — Reads entire file into an array
Description
$filename
[, int $flags = 0
[, resource $context
]] ) : arrayReads an entire file into an array.
Note:
You can use file_get_contents() to return the contents of a file as a string.
Parameters
-
filename -
Path to the file.
TipA URL can be used as a filename with this function if the fopen wrappers have been enabled. See fopen() for more details on how to specify the filename. See the Supported Protocols and Wrappers for links to information about what abilities the various wrappers have, notes on their usage, and information on any predefined variables they may provide.
-
flags -
The optional parameter
flagscan be one, or more, of the following constants:-
FILE_USE_INCLUDE_PATH - Search for the file in the include_path.
-
FILE_IGNORE_NEW_LINES - Omit newline at the end of each array element
-
FILE_SKIP_EMPTY_LINES - Skip empty lines
-
-
context -
A context resource created with the stream_context_create() function.
Note: Context support was added with PHP 5.0.0. For a description of
contexts, refer to Streams.
Return Values
Returns the file in an array. Each element of the array corresponds to a
line in the file, with the newline still attached. Upon failure,
file() returns FALSE.
Note:
Each line in the resulting array will include the line ending, unless
FILE_IGNORE_NEW_LINESis used.
Note: If PHP is not properly recognizing the line endings when reading files either on or created by a Macintosh computer, enabling the auto_detect_line_endings run-time configuration option may help resolve the problem.
Errors/Exceptions
Emits an E_WARNING level error if the file
does not exist.
Examples
Example #1 file() example
<?php
// Get a file into an array. In this example we'll go through HTTP to get
// the HTML source of a URL.
$lines = file('http://www.example.com/');
// Loop through our array, show HTML source as HTML source; and line numbers too.
foreach ($lines as $line_num => $line) {
echo "Line #<b>{$line_num}</b> : " . htmlspecialchars($line) . "<br />\n";
}
// Another example, let's get a web page into a string. See also file_get_contents().
$html = implode('', file('http://www.example.com/'));
// Using the optional flags parameter since PHP 5
$trimmed = file('somefile.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
?>
Notes
When using SSL, Microsoft IIS
will violate the protocol by closing the connection without sending a
close_notify indicator. PHP will report this as "SSL: Fatal
Protocol Error" when you reach the end of the data. To work around this, the
value of error_reporting should be
lowered to a level that does not include warnings.
PHP can detect buggy IIS server software when you open
the stream using the https:// wrapper and will suppress the
warning. When using fsockopen() to create an
ssl:// socket, the developer is responsible for detecting
and suppressing this warning.
See Also
- readfile() - Outputs a file
- fopen() - Opens file or URL
- fsockopen() - Open Internet or Unix domain socket connection
- popen() - Opens process file pointer
- file_get_contents() - Reads entire file into a string
- include - include
- stream_context_create() - Creates a stream context
fileatime
(PHP 4, PHP 5, PHP 7)
fileatime — Gets last access time of file
Description
$filename
) : intGets the last access time of the given file.
Parameters
-
filename -
Path to the file.
Return Values
Returns the time the file was last accessed, or FALSE on failure.
The time is returned as a Unix timestamp.
Examples
Example #1 fileatime() example
<?php
// outputs e.g. somefile.txt was last accessed: December 29 2002 22:16:23.
$filename = 'somefile.txt';
if (file_exists($filename)) {
echo "$filename was last accessed: " . date("F d Y H:i:s.", fileatime($filename));
}
?>
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note:
The atime of a file is supposed to change whenever the data blocks of a file are being read. This can be costly performance-wise when an application regularly accesses a very large number of files or directories.
Some Unix filesystems can be mounted with atime updates disabled to increase the performance of such applications; USENET news spools are a common example. On such filesystems this function will be useless.
Note:
Note that time resolution may differ from one file system to another.
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
See Also
- filemtime() - Gets file modification time
- fileinode() - Gets file inode
- date() - Format a local time/date
filectime
(PHP 4, PHP 5, PHP 7)
filectime — Gets inode change time of file
Description
$filename
) : intGets the inode change time of a file.
Parameters
-
filename -
Path to the file.
Return Values
Returns the time the file was last changed, or FALSE on failure.
The time is returned as a Unix timestamp.
Examples
Example #1 A filectime() example
<?php
// outputs e.g. somefile.txt was last changed: December 29 2002 22:16:23.
$filename = 'somefile.txt';
if (file_exists($filename)) {
echo "$filename was last changed: " . date("F d Y H:i:s.", filectime($filename));
}
?>
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note:
Note: In most Unix filesystems, a file is considered changed when its inode data is changed; that is, when the permissions, owner, group, or other metadata from the inode is updated. See also filemtime() (which is what you want to use when you want to create "Last Modified" footers on web pages) and fileatime().
Note:
Note also that in some Unix texts the ctime of a file is referred to as being the creation time of the file. This is wrong. There is no creation time for Unix files in most Unix filesystems.
Note:
Note that time resolution may differ from one file system to another.
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
filegroup
(PHP 4, PHP 5, PHP 7)
filegroup — Gets file group
Description
$filename
) : intGets the file group. The group ID is returned in numerical format, use posix_getgrgid() to resolve it to a group name.
Parameters
-
filename -
Path to the file.
Return Values
Returns the group ID of the file, or FALSE if
an error occurs. The group ID is returned in numerical format, use
posix_getgrgid() to resolve it to a group name.
Upon failure, FALSE is returned.
Examples
Example #1 Finding the group of a file
<?php
$filename = 'index.php';
print_r(posix_getgrgid(filegroup($filename)));
?>
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
See Also
- fileowner() - Gets file owner
- posix_getgrgid() - Return info about a group by group id
- safe_mode_gid
fileinode
(PHP 4, PHP 5, PHP 7)
fileinode — Gets file inode
Description
$filename
) : intGets the file inode.
Parameters
-
filename -
Path to the file.
Return Values
Returns the inode number of the file, or FALSE on failure.
Examples
Example #1 Comparing the inode of a file with the current file
<?php
$filename = 'index.php';
if (getmyinode() == fileinode($filename)) {
echo 'You are checking the current file.';
}
?>
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
See Also
- getmyinode() - Gets the inode of the current script
- stat() - Gives information about a file
filemtime
(PHP 4, PHP 5, PHP 7)
filemtime — Gets file modification time
Description
$filename
) : intThis function returns the time when the data blocks of a file were being written to, that is, the time when the content of the file was changed.
Parameters
-
filename -
Path to the file.
Return Values
Returns the time the file was last modified, or FALSE on failure.
The time is returned as a Unix timestamp, which is
suitable for the date() function.
Examples
Example #1 filemtime() example
<?php
// outputs e.g. somefile.txt was last modified: December 29 2002 22:16:23.
$filename = 'somefile.txt';
if (file_exists($filename)) {
echo "$filename was last modified: " . date ("F d Y H:i:s.", filemtime($filename));
}
?>
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note:
Note that time resolution may differ from one file system to another.
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
See Also
- filectime() - Gets inode change time of file
- stat() - Gives information about a file
- touch() - Sets access and modification time of file
- getlastmod() - Gets time of last page modification
fileowner
(PHP 4, PHP 5, PHP 7)
fileowner — Gets file owner
Description
$filename
) : intGets the file owner.
Parameters
-
filename -
Path to the file.
Return Values
Returns the user ID of the owner of the file, or FALSE on failure.
The user ID is returned in numerical format, use
posix_getpwuid() to resolve it to a username.
Examples
Example #1 Finding the owner of a file
<?php
$filename = 'index.php';
print_r(posix_getpwuid(fileowner($filename)));
?>
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
See Also
- filegroup() - Gets file group
- stat() - Gives information about a file
- posix_getpwuid() - Return info about a user by user id
fileperms
(PHP 4, PHP 5, PHP 7)
fileperms — Gets file permissions
Description
$filename
) : intGets permissions for the given file.
Parameters
-
filename -
Path to the file.
Return Values
Returns the file's permissions as a numeric mode. Lower bits of this mode
are the same as the permissions expected by chmod(),
however on most platforms the return value will also include information on
the type of file given as filename. The examples
below demonstrate how to test the return value for specific permissions and
file types on POSIX systems, including Linux and macOS.
For local files, the specific return value is that of the
st_mode member of the structure returned by the C
library's stat() function. Exactly which bits are set
can vary from platform to platform, and looking up your specific platform's
documentation is recommended if parsing the non-permission bits of the
return value is required.
Examples
Example #1 Display permissions as an octal value
<?php
echo substr(sprintf('%o', fileperms('/tmp')), -4);
echo substr(sprintf('%o', fileperms('/etc/passwd')), -4);
?>
The above example will output:
1777 0644
Example #2 Display full permissions
<?php
$perms = fileperms('/etc/passwd');
switch ($perms & 0xF000) {
case 0xC000: // socket
$info = 's';
break;
case 0xA000: // symbolic link
$info = 'l';
break;
case 0x8000: // regular
$info = 'r';
break;
case 0x6000: // block special
$info = 'b';
break;
case 0x4000: // directory
$info = 'd';
break;
case 0x2000: // character special
$info = 'c';
break;
case 0x1000: // FIFO pipe
$info = 'p';
break;
default: // unknown
$info = 'u';
}
// Owner
$info .= (($perms & 0x0100) ? 'r' : '-');
$info .= (($perms & 0x0080) ? 'w' : '-');
$info .= (($perms & 0x0040) ?
(($perms & 0x0800) ? 's' : 'x' ) :
(($perms & 0x0800) ? 'S' : '-'));
// Group
$info .= (($perms & 0x0020) ? 'r' : '-');
$info .= (($perms & 0x0010) ? 'w' : '-');
$info .= (($perms & 0x0008) ?
(($perms & 0x0400) ? 's' : 'x' ) :
(($perms & 0x0400) ? 'S' : '-'));
// World
$info .= (($perms & 0x0004) ? 'r' : '-');
$info .= (($perms & 0x0002) ? 'w' : '-');
$info .= (($perms & 0x0001) ?
(($perms & 0x0200) ? 't' : 'x' ) :
(($perms & 0x0200) ? 'T' : '-'));
echo $info;
?>
The above example will output:
-rw-r--r--
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
See Also
- chmod() - Changes file mode
- is_readable() - Tells whether a file exists and is readable
- stat() - Gives information about a file
filesize
(PHP 4, PHP 5, PHP 7)
filesize — Gets file size
Description
$filename
) : intGets the size for the given file.
Parameters
-
filename -
Path to the file.
Return Values
Returns the size of the file in bytes, or FALSE (and generates an error
of level E_WARNING) in case of an error.
Note: Because PHP's integer type is signed and many platforms use 32bit integers, some filesystem functions may return unexpected results for files which are larger than 2GB.
Examples
Example #1 filesize() example
<?php
// outputs e.g. somefile.txt: 1024 bytes
$filename = 'somefile.txt';
echo $filename . ': ' . filesize($filename) . ' bytes';
?>
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
filetype
(PHP 4, PHP 5, PHP 7)
filetype — Gets file type
Description
$filename
) : stringReturns the type of the given file.
Parameters
-
filename -
Path to the file.
Return Values
Returns the type of the file. Possible values are fifo, char, dir, block, link, file, socket and unknown.
Returns FALSE if an error occurs. filetype() will also
produce an E_NOTICE message if the stat call fails
or if the file type is unknown.
Examples
Example #1 filetype() example
<?php
echo filetype('/etc/passwd'); // file
echo filetype('/etc/'); // dir
?>
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
See Also
- is_dir() - Tells whether the filename is a directory
- is_file() - Tells whether the filename is a regular file
- is_link() - Tells whether the filename is a symbolic link
- file_exists() - Checks whether a file or directory exists
- mime_content_type() - Detect MIME Content-type for a file
- pathinfo() - Returns information about a file path
- stat() - Gives information about a file
flock
(PHP 4, PHP 5, PHP 7)
flock — Portable advisory file locking
Description
$handle
, int $operation
[, int &$wouldblock
] ) : boolflock() allows you to perform a simple reader/writer model which can be used on virtually every platform (including most Unix derivatives and even Windows).
On versions of PHP before 5.3.2, the lock is released also by fclose() (which is also called automatically when script finished).
PHP supports a portable way of locking complete files in an advisory way
(which means all accessing programs have to use the same way of locking
or it will not work). By default, this function will block until the
requested lock is acquired; this may be controlled with the LOCK_NB option documented below.
Parameters
-
handle -
A file system pointer resource that is typically created using fopen().
-
operation -
operationis one of the following:-
LOCK_SHto acquire a shared lock (reader). -
LOCK_EXto acquire an exclusive lock (writer). -
LOCK_UNto release a lock (shared or exclusive).
It is also possible to add
LOCK_NBas a bitmask to one of the above operations, if flock() should not block during the locking attempt. -
-
wouldblock -
The optional third argument is set to 1 if the lock would block (EWOULDBLOCK errno condition).
Return Values
Returns TRUE on success or FALSE on failure.
Changelog
| Version | Description |
|---|---|
| 5.5.22, 5.6.6 |
Added support for the wouldblock parameter on
Windows.
|
| 5.3.2 | The automatic unlocking when the file's resource handle is closed was removed. Unlocking now always has to be done manually. |
Examples
Example #1 flock() example
<?php
$fp = fopen("/tmp/lock.txt", "r+");
if (flock($fp, LOCK_EX)) { // acquire an exclusive lock
ftruncate($fp, 0); // truncate file
fwrite($fp, "Write something here\n");
fflush($fp); // flush output before releasing the lock
flock($fp, LOCK_UN); // release the lock
} else {
echo "Couldn't get the lock!";
}
fclose($fp);
?>
Example #2 flock() using the LOCK_NB option
<?php
$fp = fopen('/tmp/lock.txt', 'r+');
/* Activate the LOCK_NB option on an LOCK_EX operation */
if(!flock($fp, LOCK_EX | LOCK_NB)) {
echo 'Unable to obtain lock';
exit(-1);
}
/* ... */
fclose($fp);
?>
Notes
Note:
flock() uses mandatory locking instead of advisory locking on Windows. Mandatory locking is also supported on Linux and System V based operating systems via the usual mechanism supported by the fcntl() system call: that is, if the file in question has the setgid permission bit set and the group execution bit cleared. On Linux, the file system will also need to be mounted with the mand option for this to work.
Note:
Because flock() requires a file pointer, you may have to use a special lock file to protect access to a file that you intend to truncate by opening it in write mode (with a "w" or "w+" argument to fopen()).
Note:
May only be used on file pointers returned by fopen() for local files, or file pointers pointing to userspace streams that implement the streamWrapper::stream_lock() method.
Assigning another value to handle argument in
subsequent code will release the lock.
On some operating systems flock() is implemented at the process level. When using a multithreaded server API like ISAPI you may not be able to rely on flock() to protect files against other PHP scripts running in parallel threads of the same server instance!
flock() is not supported on antiquated filesystems like
FAT and its derivates and will therefore always
return FALSE under these environments.
fnmatch
(PHP 4 >= 4.3.0, PHP 5, PHP 7)
fnmatch — Match filename against a pattern
Description
$pattern
, string $string
[, int $flags = 0
] ) : bool
fnmatch() checks if the passed string would
match the given shell wildcard pattern.
Parameters
-
pattern -
The shell wildcard pattern.
-
string -
The tested string. This function is especially useful for filenames, but may also be used on regular strings.
The average user may be used to shell patterns or at least in their simplest form to
'?'and'*'wildcards so using fnmatch() instead of preg_match() for frontend search expression input may be way more convenient for non-programming users. -
flags -
The value of
flagscan be any combination of the following flags, joined with the binary OR (|) operator.A list of possible flags for fnmatch() FlagDescription FNM_NOESCAPEDisable backslash escaping. FNM_PATHNAMESlash in string only matches slash in the given pattern. FNM_PERIODLeading period in string must be exactly matched by period in the given pattern. FNM_CASEFOLDCaseless match. Part of the GNU extension.
Return Values
Returns TRUE if there is a match, FALSE otherwise.
Changelog
| Version | Description |
|---|---|
| 5.3.0 | This function is now available on Windows platforms. |
Examples
Example #1 Checking a color name against a shell wildcard pattern
<?php
if (fnmatch("*gr[ae]y", $color)) {
echo "some form of gray ...";
}
?>
Notes
For now, this function is not available on non-POSIX compliant systems except Windows.
See Also
- glob() - Find pathnames matching a pattern
- preg_match() - Perform a regular expression match
- sscanf() - Parses input from a string according to a format
- printf() - Output a formatted string
- sprintf() - Return a formatted string
fopen
(PHP 4, PHP 5, PHP 7)
fopen — Opens file or URL
Description
$filename
, string $mode
[, bool $use_include_path = FALSE
[, resource $context
]] ) : resource
fopen() binds a named resource, specified by
filename, to a stream.
Parameters
-
filename -
If
filenameis of the form "scheme://...", it is assumed to be a URL and PHP will search for a protocol handler (also known as a wrapper) for that scheme. If no wrappers for that protocol are registered, PHP will emit a notice to help you track potential problems in your script and then continue as thoughfilenamespecifies a regular file.If PHP has decided that
filenamespecifies a local file, then it will try to open a stream on that file. The file must be accessible to PHP, so you need to ensure that the file access permissions allow this access. If you have enabled safe mode or open_basedir further restrictions may apply.If PHP has decided that
filenamespecifies a registered protocol, and that protocol is registered as a network URL, PHP will check to make sure that allow_url_fopen is enabled. If it is switched off, PHP will emit a warning and the fopen call will fail.Note:
The list of supported protocols can be found in Supported Protocols and Wrappers. Some protocols (also referred to as
wrappers) supportcontextand/or php.ini options. Refer to the specific page for the protocol in use for a list of options which can be set. (e.g. php.ini valueuser_agentused by thehttpwrapper).On the Windows platform, be careful to escape any backslashes used in the path to the file, or use forward slashes.
<?php
$handle = fopen("c:\\folder\\resource.txt", "r");
?> -
mode -
The
modeparameter specifies the type of access you require to the stream. It may be any of the following:A list of possible modes for fopen() using modemodeDescription 'r'Open for reading only; place the file pointer at the beginning of the file. 'r+'Open for reading and writing; place the file pointer at the beginning of the file. 'w'Open for writing only; place the file pointer at the beginning of the file and truncate the file to zero length. If the file does not exist, attempt to create it. 'w+'Open for reading and writing; place the file pointer at the beginning of the file and truncate the file to zero length. If the file does not exist, attempt to create it. 'a'Open for writing only; place the file pointer at the end of the file. If the file does not exist, attempt to create it. In this mode, fseek() has no effect, writes are always appended. 'a+'Open for reading and writing; place the file pointer at the end of the file. If the file does not exist, attempt to create it. In this mode, fseek() only affects the reading position, writes are always appended. 'x'Create and open for writing only; place the file pointer at the beginning of the file. If the file already exists, the fopen() call will fail by returning FALSEand generating an error of levelE_WARNING. If the file does not exist, attempt to create it. This is equivalent to specifyingO_EXCL|O_CREATflags for the underlyingopen(2)system call.'x+'Create and open for reading and writing; otherwise it has the same behavior as 'x'.'c'Open the file for writing only. If the file does not exist, it is created. If it exists, it is neither truncated (as opposed to 'w'), nor the call to this function fails (as is the case with'x'). The file pointer is positioned on the beginning of the file. This may be useful if it's desired to get an advisory lock (see flock()) before attempting to modify the file, as using'w'could truncate the file before the lock was obtained (if truncation is desired, ftruncate() can be used after the lock is requested).'c+'Open the file for reading and writing; otherwise it has the same behavior as 'c'.'e'Set close-on-exec flag on the opened file descriptor. Only available in PHP compiled on POSIX.1-2008 conform systems. Note:
Different operating system families have different line-ending conventions. When you write a text file and want to insert a line break, you need to use the correct line-ending character(s) for your operating system. Unix based systems use
\nas the line ending character, Windows based systems use\r\nas the line ending characters and Macintosh based systems (Mac OS Classic) used\ras the line ending character.If you use the wrong line ending characters when writing your files, you might find that other applications that open those files will "look funny".
Windows offers a text-mode translation flag (
't') which will transparently translate\nto\r\nwhen working with the file. In contrast, you can also use'b'to force binary mode, which will not translate your data. To use these flags, specify either'b'or't'as the last character of themodeparameter.The default translation mode is
'b'. You can use the't'mode if you are working with plain-text files and you use\nto delimit your line endings in your script, but expect your files to be readable with applications such as old versions of notepad. You should use the'b'in all other cases.If you specify the 't' flag when working with binary files, you may experience strange problems with your data, including broken image files and strange problems with
\r\ncharacters.Note:
For portability, it is also strongly recommended that you re-write code that uses or relies upon the
't'mode so that it uses the correct line endings and'b'mode instead. -
use_include_path -
The optional third
use_include_pathparameter can be set to '1' orTRUEif you want to search for the file in the include_path, too. -
context -
Note: Context support was added with PHP 5.0.0. For a description of
contexts, refer to Streams.
Return Values
Returns a file pointer resource on success,
or FALSE on failure
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Changelog
| Version | Description |
|---|---|
| 7.0.16, 7.1.2 |
The 'e' option was added.
|
| 5.2.6 |
The 'c' and 'c+' options were
added
|
Examples
Example #1 fopen() examples
<?php
$handle = fopen("/home/rasmus/file.txt", "r");
$handle = fopen("/home/rasmus/file.gif", "wb");
$handle = fopen("http://www.example.com/", "r");
$handle = fopen("ftp://user:password@example.com/somefile.txt", "w");
?>
Notes
When using SSL, Microsoft IIS
will violate the protocol by closing the connection without sending a
close_notify indicator. PHP will report this as "SSL: Fatal
Protocol Error" when you reach the end of the data. To work around this, the
value of error_reporting should be
lowered to a level that does not include warnings.
PHP can detect buggy IIS server software when you open
the stream using the https:// wrapper and will suppress the
warning. When using fsockopen() to create an
ssl:// socket, the developer is responsible for detecting
and suppressing this warning.
Note: When safe mode is enabled, PHP checks whether the directory in which the script is operating has the same UID (owner) as the script that is being executed.
Note:
If you are experiencing problems with reading and writing to files and you're using the server module version of PHP, remember to make sure that the files and directories you're using are accessible to the server process.
Note:
This function may also succeed when
filenameis a directory. If you are unsure whetherfilenameis a file or a directory, you may need to use the is_dir() function before calling fopen().
See Also
- Supported Protocols and Wrappers
- fclose() - Closes an open file pointer
- fgets() - Gets line from file pointer
- fread() - Binary-safe file read
- fwrite() - Binary-safe file write
- fsockopen() - Open Internet or Unix domain socket connection
- file() - Reads entire file into an array
- file_exists() - Checks whether a file or directory exists
- is_readable() - Tells whether a file exists and is readable
- stream_set_timeout() - Set timeout period on a stream
- popen() - Opens process file pointer
- stream_context_create() - Creates a stream context
- umask() - Changes the current umask
- SplFileObject
fpassthru
(PHP 4, PHP 5, PHP 7)
fpassthru — Output all remaining data on a file pointer
Description
$handle
) : intReads to EOF on the given file pointer from the current position and writes the results to the output buffer.
You may need to call rewind() to reset the file pointer to the beginning of the file if you have already written data to the file.
If you just want to dump the contents of a file to the output buffer, without first modifying it or seeking to a particular offset, you may want to use the readfile(), which saves you the fopen() call.
Parameters
-
handle -
The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen() (and not yet closed by fclose()).
Return Values
If an error occurs, fpassthru() returns
FALSE. Otherwise, fpassthru() returns
the number of characters read from handle
and passed through to the output.
Examples
Example #1 Using fpassthru() with binary files
<?php
// open the file in a binary mode
$name = './img/ok.png';
$fp = fopen($name, 'rb');
// send the right headers
header("Content-Type: image/png");
header("Content-Length: " . filesize($name));
// dump the picture and stop the script
fpassthru($fp);
exit;
?>
Notes
Note:
When using fpassthru() on a binary file on Windows systems, you should make sure to open the file in binary mode by appending a
bto the mode used in the call to fopen().You are encouraged to use the
bflag when dealing with binary files, even if your system does not require it, so that your scripts will be more portable.
See Also
- readfile() - Outputs a file
- fopen() - Opens file or URL
- popen() - Opens process file pointer
- fsockopen() - Open Internet or Unix domain socket connection
fputcsv
(PHP 5 >= 5.1.0, PHP 7)
fputcsv — Format line as CSV and write to file pointer
Description
$handle
, array $fields
[, string $delimiter = ","
[, string $enclosure = '"'
[, string $escape_char = "\\"
]]] ) : int
fputcsv() formats a line (passed as a
fields array) as CSV and writes it (terminated by a
newline) to the specified file handle.
Parameters
-
handle -
The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen() (and not yet closed by fclose()).
-
fields -
An array of strings.
-
delimiter -
The optional
delimiterparameter sets the field delimiter (one character only). -
enclosure -
The optional
enclosureparameter sets the field enclosure (one character only). -
escape_char -
The optional
escape_charparameter sets the escape character (at most one character). An empty string ("") disables the proprietary escape mechanism.
Note:
If an
enclosurecharacter is contained in a field, it will be escaped by doubling it, unless it is immediately preceded by anescape_char.
Return Values
Returns the length of the written string or FALSE on failure.
Changelog
| Version | Description |
|---|---|
| 7.4.0 |
The escape_char parameter now also accepts an empty
string to disable the proprietary escape mechanism.
|
| 5.5.4 |
The escape_char parameter was added
|
Examples
Example #1 fputcsv() example
<?php
$list = array (
array('aaa', 'bbb', 'ccc', 'dddd'),
array('123', '456', '789'),
array('"aaa"', '"bbb"')
);
$fp = fopen('file.csv', 'w');
foreach ($list as $fields) {
fputcsv($fp, $fields);
}
fclose($fp);
?>
The above example will write the following to file.csv:
aaa,bbb,ccc,dddd 123,456,789 """aaa""","""bbb"""
Notes
Note: If PHP is not properly recognizing the line endings when reading files either on or created by a Macintosh computer, enabling the auto_detect_line_endings run-time configuration option may help resolve the problem.
Description
This function is an alias of: fwrite().
fread
(PHP 4, PHP 5, PHP 7)
fread — Binary-safe file read
Description
$handle
, int $length
) : string
fread() reads up to
length bytes from the file pointer
referenced by handle. Reading stops as soon as one
of the following conditions is met:
-
lengthbytes have been read - EOF (end of file) is reached
- a packet becomes available or the socket timeout occurs (for network streams)
- if the stream is read buffered and it does not represent a plain file, at most one read of up to a number of bytes equal to the chunk size (usually 8192) is made; depending on the previously buffered data, the size of the returned data may be larger than the chunk size.
Parameters
Return Values
Returns the read string or FALSE on failure.
Examples
Example #1 A simple fread() example
<?php
// get contents of a file into a string
$filename = "/usr/local/something.txt";
$handle = fopen($filename, "r");
$contents = fread($handle, filesize($filename));
fclose($handle);
?>
Example #2 Binary fread() example
On systems which differentiate between binary and text files (i.e. Windows) the file must be opened with 'b' included in fopen() mode parameter.
<?php
$filename = "c:\\files\\somepic.gif";
$handle = fopen($filename, "rb");
$contents = fread($handle, filesize($filename));
fclose($handle);
?>
Example #3 Remote fread() examples
When reading from anything that is not a regular local file, such as streams returned when reading remote files or from popen() and fsockopen(), reading will stop after a packet is available. This means that you should collect the data together in chunks as shown in the examples below.
<?php
// For PHP 5 and up
$handle = fopen("http://www.example.com/", "rb");
$contents = stream_get_contents($handle);
fclose($handle);
?>
<?php
$handle = fopen("http://www.example.com/", "rb");
if (FALSE === $handle) {
exit("Failed to open stream to URL");
}
$contents = '';
while (!feof($handle)) {
$contents .= fread($handle, 8192);
}
fclose($handle);
?>
Notes
Note:
If you just want to get the contents of a file into a string, use file_get_contents() as it has much better performance than the code above.
Note:
Note that fread() reads from the current position of the file pointer. Use ftell() to find the current position of the pointer and rewind() to rewind the pointer position.
See Also
- fwrite() - Binary-safe file write
- fopen() - Opens file or URL
- fsockopen() - Open Internet or Unix domain socket connection
- popen() - Opens process file pointer
- fgets() - Gets line from file pointer
- fgetss() - Gets line from file pointer and strip HTML tags
- fscanf() - Parses input from a file according to a format
- file() - Reads entire file into an array
- fpassthru() - Output all remaining data on a file pointer
- ftell() - Returns the current position of the file read/write pointer
- rewind() - Rewind the position of a file pointer
- unpack() - Unpack data from binary string
fscanf
(PHP 4 >= 4.0.1, PHP 5, PHP 7)
fscanf — Parses input from a file according to a format
Description
The function fscanf() is similar to
sscanf(), but it takes its input from a file
associated with handle and interprets the
input according to the specified format, which is
described in the documentation for sprintf().
Any whitespace in the format string matches any whitespace in the input
stream. This means that even a tab \t in the format
string can match a single space character in the input stream.
Each call to fscanf() reads one line from the file.
Parameters
-
handle -
A file system pointer resource that is typically created using fopen().
-
format -
The format string is composed of zero or more directives: ordinary characters (excluding
%) that are copied directly to the result and conversion specifications, each of which results in fetching its own parameter.A conversion specification follows this prototype:
%[argnum$][flags][width][.precision]specifier.Argnum
An integer followed by a dollar sign
$, to specify which number argument to treat in the conversion.Flags Flag Description -Left-justify within the given field width; Right justification is the default +Prefix positive numbers with a plus sign +; Default only negative are prefixed with a negative sign.Pads the result with spaces. This is the default. 0Only left-pads numbers with zeros. With sspecifiers this can also right-pad with zeros.'(char)Pads the result with the character (char). Width
An integer that says how many characters (minimum) this conversion should result in.
Precision
A period
.followed by an integer who's meaning depends on the specifier:-
For
e,E,fandFspecifiers: this is the number of digits to be printed after the decimal point (by default, this is 6). -
For
gandGspecifiers: this is the maximum number of significant digits to be printed. -
For
sspecifier: it acts as a cutoff point, setting a maximum character limit to the string.
Note: If the period is specified without an explicit value for precision, 0 is assumed.
Note: Attempting to use a position specifier greater than
PHP_INT_MAXwill generate warnings.Specifiers Specifier Description %A literal percent character. No argument is required. bThe argument is treated as an integer and presented as a binary number. cThe argument is treated as an integer and presented as the character with that ASCII. dThe argument is treated as an integer and presented as a (signed) decimal number. eThe argument is treated as scientific notation (e.g. 1.2e+2). The precision specifier stands for the number of digits after the decimal point since PHP 5.2.1. In earlier versions, it was taken as number of significant digits (one less). ELike the especifier but uses uppercase letter (e.g. 1.2E+2).fThe argument is treated as a float and presented as a floating-point number (locale aware). FThe argument is treated as a float and presented as a floating-point number (non-locale aware). Available as of PHP 5.0.3. gGeneral format.
Let P equal the precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero. Then, if a conversion with style E would have an exponent of X:
If P > X ≥ −4, the conversion is with style f and precision P − (X + 1). Otherwise, the conversion is with style e and precision P − 1.
GLike the gspecifier but usesEandf.oThe argument is treated as an integer and presented as an octal number. sThe argument is treated and presented as a string. uThe argument is treated as an integer and presented as an unsigned decimal number. xThe argument is treated as an integer and presented as a hexadecimal number (with lowercase letters). XThe argument is treated as an integer and presented as a hexadecimal number (with uppercase letters). WarningThe
ctype specifier ignores padding and widthWarningAttempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results
Variables will be co-erced to a suitable type for the specifier:
Type Handling Type Specifiers stringsintegerd,u,c,o,x,X,bdoubleg,G,e,E,f,F -
For
-
... -
The optional assigned values.
Return Values
If only two parameters were passed to this function, the values parsed will be returned as an array. Otherwise, if optional parameters are passed, the function will return the number of assigned values. The optional parameters must be passed by reference.
Examples
Example #1 fscanf() Example
<?php
$handle = fopen("users.txt", "r");
while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
list ($name, $profession, $countrycode) = $userinfo;
//... do something with the values
}
fclose($handle);
?>
Example #2 Contents of users.txt
javier argonaut pe hiroshi sculptor jp robert slacker us luigi florist it
fseek
(PHP 4, PHP 5, PHP 7)
fseek — Seeks on a file pointer
Description
$handle
, int $offset
[, int $whence = SEEK_SET
] ) : int
Sets the file position indicator for the file referenced by
handle. The new position, measured in bytes
from the beginning of the file, is obtained by adding
offset to the position specified by
whence.
In general, it is allowed to seek past the end-of-file; if data is then written, reads in any unwritten region between the end-of-file and the sought position will yield bytes with value 0. However, certain streams may not support this behavior, especially when they have an underlying fixed size storage.
Parameters
-
handle -
A file system pointer resource that is typically created using fopen().
-
offset -
The offset.
To move to a position before the end-of-file, you need to pass a negative value in
offsetand setwhencetoSEEK_END. -
whence -
whencevalues are:SEEK_SET- Set position equal tooffsetbytes.SEEK_CUR- Set position to current location plusoffset.SEEK_END- Set position to end-of-file plusoffset.
Return Values
Upon success, returns 0; otherwise, returns -1.
Examples
Example #1 fseek() example
<?php
$fp = fopen('somefile.txt', 'r');
// read some data
$data = fgets($fp, 4096);
// move back to the beginning of the file
// same as rewind($fp);
fseek($fp, 0);
?>
Notes
Note:
If you have opened the file in append (
aora+) mode, any data you write to the file will always be appended, regardless of the file position, and the result of calling fseek() will be undefined.
Note:
Not all streams support seeking. For those that do not support seeking, forward seeking from the current position is accomplished by reading and discarding data; other forms of seeking will fail.
fstat
(PHP 4, PHP 5, PHP 7)
fstat — Gets information about a file using an open file pointer
Description
$handle
) : array
Gathers the statistics of the file opened by the file
pointer handle. This function is similar to the
stat() function except that it operates
on an open file pointer instead of a filename.
Return Values
Returns an array with the statistics of the file; the format of the array is described in detail on the stat() manual page.
Examples
Example #1 fstat() example
<?php
// open a file
$fp = fopen("/etc/passwd", "r");
// gather statistics
$fstat = fstat($fp);
// close the file
fclose($fp);
// print only the associative part
print_r(array_slice($fstat, 13));
?>
The above example will output something similar to:
Array
(
[dev] => 771
[ino] => 488704
[mode] => 33188
[nlink] => 1
[uid] => 0
[gid] => 0
[rdev] => 0
[size] => 1114
[atime] => 1061067181
[mtime] => 1056136526
[ctime] => 1056136526
[blksize] => 4096
[blocks] => 8
)
Notes
Note: This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.
ftell
(PHP 4, PHP 5, PHP 7)
ftell — Returns the current position of the file read/write pointer
Description
$handle
) : int
Returns the position of the file pointer referenced by handle.
Parameters
Return Values
Returns the position of the file pointer referenced by
handle as an integer; i.e., its offset into the file stream.
If an error occurs, returns FALSE.
Note: Because PHP's integer type is signed and many platforms use 32bit integers, some filesystem functions may return unexpected results for files which are larger than 2GB.
Examples
Example #1 ftell() example
<?php
// opens a file and read some data
$fp = fopen("/etc/passwd", "r");
$data = fgets($fp, 12);
// where are we ?
echo ftell($fp); // 11
fclose($fp);
?>
ftruncate
(PHP 4, PHP 5, PHP 7)
ftruncate — Truncates a file to a given length
Description
$handle
, int $size
) : bool
Takes the filepointer, handle, and truncates the file to
length, size.
Parameters
-
handle -
The file pointer.
Note:
The
handlemust be open for writing. -
size -
The size to truncate to.
Note:
If
sizeis larger than the file then the file is extended with null bytes.If
sizeis smaller than the file then the file is truncated to that size.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 File truncation example
<?php
$filename = 'lorem_ipsum.txt';
$handle = fopen($filename, 'r+');
ftruncate($handle, rand(1, filesize($filename)));
rewind($handle);
echo fread($handle, filesize($filename));
fclose($handle);
?>
Notes
Note:
The file pointer is not changed.
fwrite
(PHP 4, PHP 5, PHP 7)
fwrite — Binary-safe file write
Description
$handle
, string $string
[, int $length
] ) : int
fwrite() writes the contents of
string to the file stream pointed to by
handle.
Parameters
-
handle -
A file system pointer resource that is typically created using fopen().
-
string -
The string that is to be written.
-
length -
If the
lengthargument is given, writing will stop afterlengthbytes have been written or the end ofstringis reached, whichever comes first.Note that if the
lengthargument is given, then the magic_quotes_runtime configuration option will be ignored and no slashes will be stripped fromstring.
Return Values
fwrite() returns the number of bytes
written, or FALSE on error.
Notes
Note:
Writing to a network stream may end before the whole string is written. Return value of fwrite() may be checked:
<?php
function fwrite_stream($fp, $string) {
for ($written = 0; $written < strlen($string); $written += $fwrite) {
$fwrite = fwrite($fp, substr($string, $written));
if ($fwrite === false) {
return $written;
}
}
return $written;
}
?>
Note:
On systems which differentiate between binary and text files (i.e. Windows) the file must be opened with 'b' included in fopen() mode parameter.
Note:
If
handlewas fopen()ed in append mode, fwrite()s are atomic (unless the size ofstringexceeds the filesystem's block size, on some platforms, and as long as the file is on a local filesystem). That is, there is no need to flock() a resource before calling fwrite(); all of the data will be written without interruption.
Note:
If writing twice to the file pointer, then the data will be appended to the end of the file content:
<?php
$fp = fopen('data.txt', 'w');
fwrite($fp, '1');
fwrite($fp, '23');
fclose($fp);
// the content of 'data.txt' is now 123 and not 23!
?>
Examples
Example #1 A simple fwrite() example
<?php
$filename = 'test.txt';
$somecontent = "Add this to the file\n";
// Let's make sure the file exists and is writable first.
if (is_writable($filename)) {
// In our example we're opening $filename in append mode.
// The file pointer is at the bottom of the file hence
// that's where $somecontent will go when we fwrite() it.
if (!$handle = fopen($filename, 'a')) {
echo "Cannot open file ($filename)";
exit;
}
// Write $somecontent to our opened file.
if (fwrite($handle, $somecontent) === FALSE) {
echo "Cannot write to file ($filename)";
exit;
}
echo "Success, wrote ($somecontent) to file ($filename)";
fclose($handle);
} else {
echo "The file $filename is not writable";
}
?>
See Also
- fread() - Binary-safe file read
- fopen() - Opens file or URL
- fsockopen() - Open Internet or Unix domain socket connection
- popen() - Opens process file pointer
- file_get_contents() - Reads entire file into a string
- pack() - Pack data into binary string
glob
(PHP 4 >= 4.3.0, PHP 5, PHP 7)
glob — Find pathnames matching a pattern
Description
$pattern
[, int $flags = 0
] ) : array
The glob() function searches for all the pathnames
matching pattern according to the rules used by
the libc glob() function, which is similar to the rules used by common
shells.
Parameters
-
pattern -
The pattern. No tilde expansion or parameter substitution is done.
Special characters:
-
*- Matches zero or more characters. -
?- Matches exactly one character (any character). -
[...]- Matches one character from a group of characters. If the first character is!, matches any character not in the group. -
\- Escapes the following character, except when theGLOB_NOESCAPEflag is used.
-
-
flags -
Valid flags:
-
GLOB_MARK- Adds a slash (a backslash on Windows) to each directory returned -
GLOB_NOSORT- Return files as they appear in the directory (no sorting). When this flag is not used, the pathnames are sorted alphabetically -
GLOB_NOCHECK- Return the search pattern if no files matching it were found -
GLOB_NOESCAPE- Backslashes do not quote metacharacters -
GLOB_BRACE- Expands {a,b,c} to match 'a', 'b', or 'c' -
GLOB_ONLYDIR- Return only directory entries which match the pattern -
GLOB_ERR- Stop on read errors (like unreadable directories), by default errors are ignored.
-
Return Values
Returns an array containing the matched files/directories, an empty array
if no file matched or FALSE on error.
Note:
On some systems it is impossible to distinguish between empty match and an error.
Changelog
| Version | Description |
|---|---|
| 5.1.0 |
GLOB_ERR was added
|
Examples
Example #1 Convenient way how glob() can replace opendir() and friends.
<?php
foreach (glob("*.txt") as $filename) {
echo "$filename size " . filesize($filename) . "\n";
}
?>
The above example will output something similar to:
funclist.txt size 44686 funcsummary.txt size 267625 quickref.txt size 137820
Notes
Note: This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.
Note: This function isn't available on some systems (e.g. old Sun OS).
Note: The
GLOB_BRACEflag is not available on some non GNU systems, like Solaris.
See Also
- opendir() - Open directory handle
- readdir() - Read entry from directory handle
- closedir() - Close directory handle
- fnmatch() - Match filename against a pattern
is_dir
(PHP 4, PHP 5, PHP 7)
is_dir — Tells whether the filename is a directory
Description
$filename
) : boolTells whether the given filename is a directory.
Parameters
-
filename -
Path to the file. If
filenameis a relative filename, it will be checked relative to the current working directory. Iffilenameis a symbolic or hard link then the link will be resolved and checked. If you have enabled safe mode, or open_basedir further restrictions may apply.
Return Values
Returns TRUE if the filename exists and is a directory, FALSE
otherwise.
Examples
Example #1 is_dir() example
<?php
var_dump(is_dir('a_file.txt'));
var_dump(is_dir('bogus_dir/abc'));
var_dump(is_dir('..')); //one dir up
?>
The above example will output:
bool(false) bool(false) bool(true)
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
is_executable
(PHP 4, PHP 5, PHP 7)
is_executable — Tells whether the filename is executable
Description
$filename
) : boolTells whether the filename is executable.
Parameters
-
filename -
Path to the file.
Return Values
Returns TRUE if the filename exists and is executable, or FALSE on
error.
Examples
Example #1 is_executable() example
<?php
$file = '/home/vincent/somefile.sh';
if (is_executable($file)) {
echo $file.' is executable';
} else {
echo $file.' is not executable';
}
?>
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
is_file
(PHP 4, PHP 5, PHP 7)
is_file — Tells whether the filename is a regular file
Description
$filename
) : boolTells whether the given file is a regular file.
Parameters
-
filename -
Path to the file.
Return Values
Returns TRUE if the filename exists and is a regular file, FALSE
otherwise.
Note: Because PHP's integer type is signed and many platforms use 32bit integers, some filesystem functions may return unexpected results for files which are larger than 2GB.
Examples
Example #1 is_file() example
<?php
var_dump(is_file('a_file.txt')) . "\n";
var_dump(is_file('/usr/bin/')) . "\n";
?>
The above example will output:
bool(true) bool(false)
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
is_link
(PHP 4, PHP 5, PHP 7)
is_link — Tells whether the filename is a symbolic link
Description
$filename
) : boolTells whether the given file is a symbolic link.
Parameters
-
filename -
Path to the file.
Return Values
Returns TRUE if the filename exists and is a symbolic link, FALSE
otherwise.
Examples
Example #1 Create and confirm if a file is a symbolic link
<?php
$link = 'uploads';
if (is_link($link)) {
echo(readlink($link));
} else {
symlink('uploads.php', $link);
}
?>
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
See Also
- is_dir() - Tells whether the filename is a directory
- is_file() - Tells whether the filename is a regular file
- readlink() - Returns the target of a symbolic link
is_readable
(PHP 4, PHP 5, PHP 7)
is_readable — Tells whether a file exists and is readable
Description
$filename
) : boolTells whether a file exists and is readable.
Parameters
-
filename -
Path to the file.
Return Values
Returns TRUE if the file or directory specified by
filename exists and is readable, FALSE otherwise.
Examples
Example #1 is_readable() example
<?php
$filename = 'test.txt';
if (is_readable($filename)) {
echo 'The file is readable';
} else {
echo 'The file is not readable';
}
?>
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Keep in mind that PHP may be accessing the file as the user id that the web server runs as (often 'nobody'). Safe mode limitations are not taken into account before PHP 5.1.5.
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
Note:
The check is done using the real UID/GID instead of the effective one.
This function may return TRUE for directories. Use
is_dir() to distinguish file and directory.
See Also
- is_writable() - Tells whether the filename is writable
- file_exists() - Checks whether a file or directory exists
- fgets() - Gets line from file pointer
is_uploaded_file
(PHP 4 >= 4.0.3, PHP 5, PHP 7)
is_uploaded_file — Tells whether the file was uploaded via HTTP POST
Description
$filename
) : bool
Returns TRUE if the file named by filename was
uploaded via HTTP POST. This is useful to help ensure that a
malicious user hasn't tried to trick the script into working on
files upon which it should not be working--for instance,
/etc/passwd.
This sort of check is especially important if there is any chance that anything done with uploaded files could reveal their contents to the user, or even to other users on the same system.
For proper working, the function is_uploaded_file() needs an argument like $_FILES['userfile']['tmp_name'], - the name of the uploaded file on the client's machine $_FILES['userfile']['name'] does not work.
Parameters
-
filename -
The filename being checked.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 is_uploaded_file() example
<?php
if (is_uploaded_file($_FILES['userfile']['tmp_name'])) {
echo "File ". $_FILES['userfile']['name'] ." uploaded successfully.\n";
echo "Displaying contents\n";
readfile($_FILES['userfile']['tmp_name']);
} else {
echo "Possible file upload attack: ";
echo "filename '". $_FILES['userfile']['tmp_name'] . "'.";
}
?>
See Also
- move_uploaded_file() - Moves an uploaded file to a new location
- $_FILES
- See Handling file uploads for a simple usage example.
is_writable
(PHP 4, PHP 5, PHP 7)
is_writable — Tells whether the filename is writable
Description
$filename
) : bool
Returns TRUE if the filename exists and is
writable. The filename argument may be a directory name allowing you
to check if a directory is writable.
Keep in mind that PHP may be accessing the file as the user id that the web server runs as (often 'nobody'). Safe mode limitations are not taken into account.
Parameters
-
filename -
The filename being checked.
Return Values
Returns TRUE if the filename exists and is
writable.
Examples
Example #1 is_writable() example
<?php
$filename = 'test.txt';
if (is_writable($filename)) {
echo 'The file is writable';
} else {
echo 'The file is not writable';
}
?>
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
See Also
- is_readable() - Tells whether a file exists and is readable
- file_exists() - Checks whether a file or directory exists
- fwrite() - Binary-safe file write
Description
This function is an alias of: is_writable().
lchgrp
(PHP 5 >= 5.1.3, PHP 7)
lchgrp — Changes group ownership of symlink
Description
Attempts to change the group of the symlink filename
to group.
Only the superuser may change the group of a symlink arbitrarily; other users may change the group of a symlink to any group of which that user is a member.
Parameters
-
filename -
Path to the symlink.
-
group -
The group specified by name or number.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 Changing the group of a symbolic link
<?php
$target = 'output.php';
$link = 'output.html';
symlink($target, $link);
lchgrp($link, 8);
?>
Notes
Note: This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.
Note: When safe mode is enabled, PHP checks whether the files or directories being operated upon have the same UID (owner) as the script that is being executed.
Note: This function is not implemented on Windows platforms.
lchown
(PHP 5 >= 5.1.3, PHP 7)
lchown — Changes user ownership of symlink
Description
Attempts to change the owner of the symlink filename
to user user.
Only the superuser may change the owner of a symlink.
Parameters
-
filename -
Path to the file.
-
user -
User name or number.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 Changing the owner of a symbolic link
<?php
$target = 'output.php';
$link = 'output.html';
symlink($target, $link);
lchown($link, 8);
?>
Notes
Note: This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.
Note: When safe mode is enabled, PHP checks whether the files or directories being operated upon have the same UID (owner) as the script that is being executed.
Note: This function is not implemented on Windows platforms.
link
(PHP 4, PHP 5, PHP 7)
link — Create a hard link
Description
$target
, string $link
) : boollink() creates a hard link.
Parameters
-
target -
Target of the link.
-
link -
The link name.
Return Values
Returns TRUE on success or FALSE on failure.
Changelog
| Version | Description |
|---|---|
| 5.3.0 | This function is now available on Windows platforms (Vista, Server 2008 or greater). |
Examples
Example #1 Creating a simple hard link
<?php
$target = 'source.ext'; // This is the file that already exists
$link = 'newfile.ext'; // This the filename that you want to link it to
link($target, $link);
?>
Notes
Note: This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.
Note: For Windows only: This function requires PHP to run in an elevated mode or with the UAC disabled.
See Also
- symlink() - Creates a symbolic link
- readlink() - Returns the target of a symbolic link
- linkinfo() - Gets information about a link
linkinfo
(PHP 4, PHP 5, PHP 7)
linkinfo — Gets information about a link
Description
$path
) : intGets information about a link.
This function is used to verify if a link (pointed to by
path) really exists (using the same method as the
S_ISLNK macro defined in stat.h).
Parameters
-
path -
Path to the link.
Return Values
linkinfo() returns the st_dev field
of the Unix C stat structure returned by the lstat
system call. Returns a non-negative integer on success, -1 in case the link was not found,
or FALSE if an open.base_dir violation occurs.
Changelog
| Version | Description |
|---|---|
| 5.3.0 | This function is now available on Windows platforms (Vista, Server 2008 or greater). |
Examples
Example #1 linkinfo() example
<?php
echo linkinfo('/vmlinuz'); // 835
?>
See Also
- symlink() - Creates a symbolic link
- link() - Create a hard link
- readlink() - Returns the target of a symbolic link
lstat
(PHP 4, PHP 5, PHP 7)
lstat — Gives information about a file or symbolic link
Description
$filename
) : array
Gathers the statistics of the file or symbolic link named by
filename.
Parameters
-
filename -
Path to a file or a symbolic link.
Return Values
See the manual page for stat() for information on
the structure of the array that lstat() returns.
This function is identical to the stat() function
except that if the filename parameter is a symbolic
link, the status of the symbolic link is returned, not the status of the
file pointed to by the symbolic link.
Examples
Example #1 Comparison of stat() and lstat()
<?php
symlink('uploads.php', 'uploads');
// Contrast information for uploads.php and uploads
array_diff(stat('uploads'), lstat('uploads'));
?>
The above example will output something similar to:
Information that differs between the two files.
Array
(
[ino] => 97236376
[mode] => 33188
[size] => 34
[atime] => 1223580003
[mtime] => 1223581848
[ctime] => 1223581848
[blocks] => 8
)
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Notes
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
mkdir
(PHP 4, PHP 5, PHP 7)
mkdir — Makes directory
Description
$pathname
[, int $mode = 0777
[, bool $recursive = FALSE
[, resource $context
]]] ) : boolAttempts to create the directory specified by pathname.
Parameters
-
pathname -
The directory path.
-
mode -
The mode is 0777 by default, which means the widest possible access. For more information on modes, read the details on the chmod() page.
Note:
modeis ignored on Windows.Note that you probably want to specify the mode as an octal number, which means it should have a leading zero. The mode is also modified by the current umask, which you can change using umask().
-
recursive -
Allows the creation of nested directories specified in the
pathname. -
context -
Note: Context support was added with PHP 5.0.0. For a description of
contexts, refer to Streams.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 mkdir() example
<?php
mkdir("/path/to/my/dir", 0700);
?>
Example #2 mkdir() using the recursive parameter
<?php
// Desired folder structure
$structure = './depth1/depth2/depth3/';
// To create the nested structure, the $recursive parameter
// to mkdir() must be specified.
if (!mkdir($structure, 0777, true)) {
die('Failed to create folders...');
}
// ...
?>
Errors/Exceptions
Emits an E_WARNING level error if the directory
already exists.
Emits an E_WARNING level error if the relevant
permissions prevent creating the directory.
Notes
Note: When safe mode is enabled, PHP checks whether the directory in which the script is operating has the same UID (owner) as the script that is being executed.
move_uploaded_file
(PHP 4 >= 4.0.3, PHP 5, PHP 7)
move_uploaded_file — Moves an uploaded file to a new location
Description
$filename
, string $destination
) : bool
This function checks to ensure that the file designated by
filename is a valid upload file (meaning
that it was uploaded via PHP's HTTP POST upload mechanism). If
the file is valid, it will be moved to the filename given by
destination.
This sort of check is especially important if there is any chance that anything done with uploaded files could reveal their contents to the user, or even to other users on the same system.
Parameters
-
filename -
The filename of the uploaded file.
-
destination -
The destination of the moved file.
Return Values
Returns TRUE on success.
If filename is not a valid upload file,
then no action will occur, and
move_uploaded_file() will return
FALSE.
If filename is a valid upload file, but
cannot be moved for some reason, no action will occur, and
move_uploaded_file() will return
FALSE. Additionally, a warning will be issued.
Examples
Example #1 Uploading multiple files
<?php
$uploads_dir = '/uploads';
foreach ($_FILES["pictures"]["error"] as $key => $error) {
if ($error == UPLOAD_ERR_OK) {
$tmp_name = $_FILES["pictures"]["tmp_name"][$key];
// basename() may prevent filesystem traversal attacks;
// further validation/sanitation of the filename may be appropriate
$name = basename($_FILES["pictures"]["name"][$key]);
move_uploaded_file($tmp_name, "$uploads_dir/$name");
}
}
?>
Notes
Note:
move_uploaded_file() is both safe mode and open_basedir aware. However, restrictions are placed only on the
destinationpath as to allow the moving of uploaded files in whichfilenamemay conflict with such restrictions. move_uploaded_file() ensures the safety of this operation by allowing only those files uploaded through PHP to be moved.
If the destination file already exists, it will be overwritten.
See Also
- is_uploaded_file() - Tells whether the file was uploaded via HTTP POST
- rename() - Renames a file or directory
- See Handling file uploads for a simple usage example
parse_ini_file
(PHP 4, PHP 5, PHP 7)
parse_ini_file — Parse a configuration file
Description
$filename
[, bool $process_sections = FALSE
[, int $scanner_mode = INI_SCANNER_NORMAL
]] ) : array
parse_ini_file() loads in the
ini file specified in filename,
and returns the settings in it in an associative array.
The structure of the ini file is the same as the php.ini's.
Parameters
-
filename -
The filename of the ini file being parsed.
-
process_sections -
By setting the
process_sectionsparameter toTRUE, you get a multidimensional array, with the section names and settings included. The default forprocess_sectionsisFALSE -
scanner_mode -
Can either be
INI_SCANNER_NORMAL(default) orINI_SCANNER_RAW. IfINI_SCANNER_RAWis supplied, then option values will not be parsed.As of PHP 5.6.1 can also be specified as
INI_SCANNER_TYPED. In this mode boolean, null and integer types are preserved when possible. String values"true","on"and"yes"are converted toTRUE."false","off","no"and"none"are consideredFALSE."null"is converted toNULLin typed mode. Also, all numeric strings are converted to integer type if it is possible.
Return Values
The settings are returned as an associative array on success,
and FALSE on failure.
Changelog
| Version | Description |
|---|---|
| 7.0.0 |
Hash marks (#) are no longer recognized as comments.
|
| 5.6.1 |
Added new INI_SCANNER_TYPED mode.
|
| 5.3.0 |
Added optional scanner_mode parameter.
Single quotes may now be used around variable assignments.
Hash marks (#) should no longer be used as comments
and will throw a deprecation warning if used.
|
| 5.2.7 |
On syntax error this function will return FALSE rather than an empty
array.
|
| 5.2.4 | Keys and section names consisting of numbers are now evaluated as PHP integers thus numbers starting by 0 are evaluated as octals and numbers starting by 0x are evaluated as hexadecimals. |
Examples
Example #1 Contents of sample.ini
; This is a sample configuration file ; Comments start with ';', as in php.ini [first_section] one = 1 five = 5 animal = BIRD [second_section] path = "/usr/local/bin" URL = "http://www.example.com/~username" [third_section] phpversion[] = "5.0" phpversion[] = "5.1" phpversion[] = "5.2" phpversion[] = "5.3" urls[svn] = "http://svn.php.net" urls[git] = "http://git.php.net"
Example #2 parse_ini_file() example
Constants may also be parsed in the ini file so if you define a constant as an ini value before running parse_ini_file(), it will be integrated into the results. Only ini values are evaluated. For example:
<?php
define('BIRD', 'Dodo bird');
// Parse without sections
$ini_array = parse_ini_file("sample.ini");
print_r($ini_array);
// Parse with sections
$ini_array = parse_ini_file("sample.ini", true);
print_r($ini_array);
?>
The above example will output something similar to:
Array
(
[one] => 1
[five] => 5
[animal] => Dodo bird
[path] => /usr/local/bin
[URL] => http://www.example.com/~username
[phpversion] => Array
(
[0] => 5.0
[1] => 5.1
[2] => 5.2
[3] => 5.3
)
[urls] => Array
(
[svn] => http://svn.php.net
[git] => http://git.php.net
)
)
Array
(
[first_section] => Array
(
[one] => 1
[five] => 5
[animal] => Dodo bird
)
[second_section] => Array
(
[path] => /usr/local/bin
[URL] => http://www.example.com/~username
)
[third_section] => Array
(
[phpversion] => Array
(
[0] => 5.0
[1] => 5.1
[2] => 5.2
[3] => 5.3
)
[urls] => Array
(
[svn] => http://svn.php.net
[git] => http://git.php.net
)
)
)
Example #3 parse_ini_file() parsing a php.ini file
<?php
// A simple function used for comparing the results below
function yesno($expression)
{
return($expression ? 'Yes' : 'No');
}
// Get the path to php.ini using the php_ini_loaded_file()
// function available as of PHP 5.2.4
$ini_path = php_ini_loaded_file();
// Parse php.ini
$ini = parse_ini_file($ini_path);
// Print and compare the values, note that using get_cfg_var()
// will give the same results for parsed and loaded here
echo '(parsed) magic_quotes_gpc = ' . yesno($ini['magic_quotes_gpc']) . PHP_EOL;
echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
?>
The above example will output something similar to:
(parsed) magic_quotes_gpc = Yes (loaded) magic_quotes_gpc = Yes
Notes
Note:
This function has nothing to do with the php.ini file. It is already processed by the time you run your script. This function can be used to read in your own application's configuration files.
Note:
If a value in the ini file contains any non-alphanumeric characters it needs to be enclosed in double-quotes (").
Note: There are reserved words which must not be used as keys for ini files. These include:
null,yes,no,true,false,on,off,none. Valuesnull,off,noandfalseresult in"", and valueson,yesandtrueresult in"1", unlessINI_SCANNER_TYPEDmode is used (as of PHP 5.6.1). Characters?{}|&~!()^"must not be used anywhere in the key and have a special meaning in the value.
Note:
Entries without an equal sign are ignored. For example, "foo" is ignored whereas "bar =" is parsed and added with an empty value. For example, MySQL has a "no-auto-rehash" setting in my.cnf that does not take a value, so it is ignored.
parse_ini_string
(PHP 5 >= 5.3.0, PHP 7)
parse_ini_string — Parse a configuration string
Description
$ini
[, bool $process_sections = FALSE
[, int $scanner_mode = INI_SCANNER_NORMAL
]] ) : array
parse_ini_string() returns the settings in string
ini in an associative array.
The structure of the ini string is the same as the php.ini's.
Parameters
-
ini -
The contents of the ini file being parsed.
-
process_sections -
By setting the
process_sectionsparameter toTRUE, you get a multidimensional array, with the section names and settings included. The default forprocess_sectionsisFALSE -
scanner_mode -
Can either be
INI_SCANNER_NORMAL(default) orINI_SCANNER_RAW. IfINI_SCANNER_RAWis supplied, then option values will not be parsed.As of PHP 5.6.1 can also be specified as
INI_SCANNER_TYPED. In this mode boolean, null and integer types are preserved when possible. String values"true","on"and"yes"are converted toTRUE."false","off","no"and"none"are consideredFALSE."null"is converted toNULLin typed mode. Also, all numeric strings are converted to integer type if it is possible.
Return Values
The settings are returned as an associative array on success,
and FALSE on failure.
Notes
Note: There are reserved words which must not be used as keys for ini files. These include:
null,yes,no,true,false,on,off,none. Valuesnull,off,noandfalseresult in"", and valueson,yesandtrueresult in"1", unlessINI_SCANNER_TYPEDmode is used. Characters?{}|&~![()^"must not be used anywhere in the key and have a special meaning in the value.
pathinfo
(PHP 4 >= 4.0.3, PHP 5, PHP 7)
pathinfo — Returns information about a file path
Description
$path
[, int $options = PATHINFO_DIRNAME | PATHINFO_BASENAME | PATHINFO_EXTENSION | PATHINFO_FILENAME
] ) : mixed
pathinfo() returns information about
path: either an associative array or a string,
depending on options.
Note:
For information on retrieving the current path info, read the section on predefined reserved variables.
pathinfo() is locale aware, so for it to parse a path containing multibyte characters correctly, the matching locale must be set using the setlocale() function.
Parameters
-
path -
The path to be parsed.
-
options -
If present, specifies a specific element to be returned; one of
PATHINFO_DIRNAME,PATHINFO_BASENAME,PATHINFO_EXTENSIONorPATHINFO_FILENAME.If
optionsis not specified, returns all available elements.
Return Values
If the options parameter is not passed, an
associative array containing the following elements is
returned:
dirname, basename,
extension (if any), and filename.
Note:
If the
pathhas more than one extension,PATHINFO_EXTENSIONreturns only the last one andPATHINFO_FILENAMEonly strips the last one. (see first example below).
Note:
If the
pathdoes not have an extension, noextensionelement will be returned (see second example below).
Note:
If the
basenameof thepathstarts with a dot, the following characters are interpreted asextension, and thefilenameis empty (see third example below).
If options is present, returns a
string containing the requested element.
Changelog
| Version | Description |
|---|---|
| 5.2.0 |
The PATHINFO_FILENAME constant was added.
|
Examples
Example #1 pathinfo() Example
<?php
$path_parts = pathinfo('/www/htdocs/inc/lib.inc.php');
echo $path_parts['dirname'], "\n";
echo $path_parts['basename'], "\n";
echo $path_parts['extension'], "\n";
echo $path_parts['filename'], "\n"; // since PHP 5.2.0
?>
The above example will output:
/www/htdocs/inc lib.inc.php php lib.inc
Example #2 pathinfo() example showing difference between null and no extension
<?php
$path_parts = pathinfo('/path/emptyextension.');
var_dump($path_parts['extension']);
$path_parts = pathinfo('/path/noextension');
var_dump($path_parts['extension']);
?>
The above example will output something similar to:
string(0) "" Notice: Undefined index: extension in test.php on line 6 NULL
Example #3 pathinfo() example for a dot-file
<?php
print_r(pathinfo('/some/path/.test'));
?>
The above example will output something similar to:
Array
(
[dirname] => /some/path
[basename] => .test
[extension] => test
[filename] =>
)
See Also
- dirname() - Returns a parent directory's path
- basename() - Returns trailing name component of path
- parse_url() - Parse a URL and return its components
- realpath() - Returns canonicalized absolute pathname
pclose
(PHP 4, PHP 5, PHP 7)
pclose — Closes process file pointer
Parameters
-
handle -
The file pointer must be valid, and must have been returned by a successful call to popen().
Return Values
Returns the termination status of the process that was run. In case of
an error then -1 is returned.
Note:
If PHP has been compiled with --enable-sigchild, the return value of this function is undefined.
Examples
Example #1 pclose() example
<?php
$handle = popen('/bin/ls', 'r');
pclose($handle);
?>
Notes
Note: Unix Only:
pclose() is internally implemented using the
waitpid(3)system call. To obtain the real exit status code the pcntl_wexitstatus() function should be used.
popen
(PHP 4, PHP 5, PHP 7)
popen — Opens process file pointer
Description
$command
, string $mode
) : resource
Opens a pipe to a process executed by forking the command given
by command.
Parameters
-
command -
The command
-
mode -
The mode
Return Values
Returns a file pointer identical to that returned by fopen(), except that it is unidirectional (may only be used for reading or writing) and must be closed with pclose(). This pointer may be used with fgets(), fgetss(), and fwrite(). When the mode is 'r', the returned file pointer equals to the STDOUT of the command, when the mode is 'w', the returned file pointer equals to the STDIN of the command.
If an error occurs, returns FALSE.
Examples
Example #1 popen() example
<?php
$handle = popen("/bin/ls", "r");
?>
If the command to be executed could not be found, a valid resource is returned. This may seem odd, but makes sense; it allows you to access any error message returned by the shell:
Example #2 popen() example
<?php
error_reporting(E_ALL);
/* Add redirection so we can get stderr. */
$handle = popen('/path/to/executable 2>&1', 'r');
echo "'$handle'; " . gettype($handle) . "\n";
$read = fread($handle, 2096);
echo $read;
pclose($handle);
?>
Notes
Note:
If you're looking for bi-directional support (two-way), use proc_open().
Note: When safe mode is enabled, you can only execute files within the safe_mode_exec_dir. For practical reasons, it is currently not allowed to have
..components in the path to the executable.
With safe mode enabled,
the command string is escaped with escapeshellcmd(). Thus,
echo y | echo x becomes echo y \| echo x.
See Also
- pclose() - Closes process file pointer
- fopen() - Opens file or URL
- proc_open() - Execute a command and open file pointers for input/output
readfile
(PHP 4, PHP 5, PHP 7)
readfile — Outputs a file
Description
$filename
[, bool $use_include_path = FALSE
[, resource $context
]] ) : intReads a file and writes it to the output buffer.
Parameters
-
filename -
The filename being read.
-
use_include_path -
You can use the optional second parameter and set it to
TRUE, if you want to search for the file in the include_path, too. -
context -
A context stream resource.
Return Values
Returns the number of bytes read from the file on success,
or FALSE on failure
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Examples
Example #1 Forcing a download using readfile()
<?php
$file = 'monkey.gif';
if (file_exists($file)) {
header('Content-Description: File Transfer');
header('Content-Type: application/octet-stream');
header('Content-Disposition: attachment; filename="'.basename($file).'"');
header('Expires: 0');
header('Cache-Control: must-revalidate');
header('Pragma: public');
header('Content-Length: ' . filesize($file));
readfile($file);
exit;
}
?>
The above example will output something similar to:
Notes
Note:
readfile() will not present any memory issues, even when sending large files, on its own. If you encounter an out of memory error ensure that output buffering is off with ob_get_level().
A URL can be used as a filename with this function if the fopen wrappers have been enabled. See fopen() for more details on how to specify the filename. See the Supported Protocols and Wrappers for links to information about what abilities the various wrappers have, notes on their usage, and information on any predefined variables they may provide.
Note: Context support was added with PHP 5.0.0. For a description of
contexts, refer to Streams.
See Also
- fpassthru() - Output all remaining data on a file pointer
- file() - Reads entire file into an array
- fopen() - Opens file or URL
- include - include
- require - require
- virtual() - Perform an Apache sub-request
- file_get_contents() - Reads entire file into a string
- Supported Protocols and Wrappers
readlink
(PHP 4, PHP 5, PHP 7)
readlink — Returns the target of a symbolic link
Description
$path
) : stringreadlink() does the same as the readlink C function.
Parameters
-
path -
The symbolic link path.
Return Values
Returns the contents of the symbolic link path or FALSE on error.
Note: The function fails if
pathis not a symlink, except on Windows, where the normalized path will be returned.
Changelog
| Version | Description |
|---|---|
| 5.3.0 | This function is now available on Windows platforms (Vista, Server 2008 or greater). |
Examples
Example #1 readlink() example
<?php
// output e.g. /boot/vmlinux-2.4.20-xfs
echo readlink('/vmlinuz');
?>
See Also
- is_link() - Tells whether the filename is a symbolic link
- symlink() - Creates a symbolic link
- linkinfo() - Gets information about a link
realpath_cache_get
(PHP 5 >= 5.3.2, PHP 7)
realpath_cache_get — Get realpath cache entries
Description
Get the contents of the realpath cache.
Return Values
Returns an array of realpath cache entries. The keys are original path entries, and the values are arrays of data items, containing the resolved path, expiration date, and other options kept in the cache.
Examples
Example #1 realpath_cache_get() example
<?php
var_dump(realpath_cache_get());
?>
The above example will output something similar to:
array(2) {
["/test"]=>
array(4) {
["key"]=>
int(123456789)
["is_dir"]=>
bool(true)
["realpath"]=>
string(5) "/test"
["expires"]=>
int(1260318939)
}
["/test/test.php"]=>
array(4) {
["key"]=>
int(987654321)
["is_dir"]=>
bool(false)
["realpath"]=>
string(12) "/root/test.php"
["expires"]=>
int(1260318939)
}
}
realpath_cache_size
(PHP 5 >= 5.3.2, PHP 7)
realpath_cache_size — Get realpath cache size
Description
Get the amount of memory used by the realpath cache.
Return Values
Returns how much memory realpath cache is using.
Examples
Example #1 realpath_cache_size() example
<?php
var_dump(realpath_cache_size());
?>
The above example will output something similar to:
int(412)
See Also
- realpath_cache_get() - Get realpath cache entries
- The realpath_cache_size configuration option
realpath
(PHP 4, PHP 5, PHP 7)
realpath — Returns canonicalized absolute pathname
Description
$path
) : string
realpath() expands all symbolic links and
resolves references to /./, /../ and extra / characters in
the input path and returns the canonicalized
absolute pathname.
Parameters
-
path -
The path being checked.
Note:
Whilst a path must be supplied, the value can be an empty string. In this case, the value is interpreted as the current directory.
Return Values
Returns the canonicalized absolute pathname on success. The resulting path
will have no symbolic link, /./ or /../ components. Trailing delimiters,
such as \ and /, are also removed.
realpath() returns FALSE on failure, e.g. if
the file does not exist.
Note:
The running script must have executable permissions on all directories in the hierarchy, otherwise realpath() will return
FALSE.
Note:
For case-insensitive filesystems realpath() may or may not normalize the character case.
Note:
The function realpath() will not work for a file which is inside a Phar as such path would be a virtual path, not a real one.
Note: Because PHP's integer type is signed and many platforms use 32bit integers, some filesystem functions may return unexpected results for files which are larger than 2GB.
Changelog
| Version | Description |
|---|---|
| 5.3.0 |
Prior to this release, if only the last path
component did not exist, realpath() would not fail on
*BSD systems. realpath() now fails in this case.
|
| 5.2.1 |
Prior to this version, realpath() returned FALSE
if path is an empty string or NULL.
|
Examples
Example #1 realpath() example
<?php
chdir('/var/www/');
echo realpath('./../../etc/passwd') . PHP_EOL;
echo realpath('/tmp/') . PHP_EOL;
?>
The above example will output:
/etc/passwd /tmp
Example #2 realpath() on Windows
On windows realpath() will change unix style paths to windows style.
<?php
echo realpath('/windows/system32'), PHP_EOL;
echo realpath('C:\Program Files\\'), PHP_EOL;
?>
The above example will output:
C:\WINDOWS\System32 C:\Program Files
See Also
- basename() - Returns trailing name component of path
- dirname() - Returns a parent directory's path
- pathinfo() - Returns information about a file path
rename
(PHP 4, PHP 5, PHP 7)
rename — Renames a file or directory
Description
$oldname
, string $newname
[, resource $context
] ) : bool
Attempts to rename oldname to
newname, moving it between directories if necessary.
If renaming a file and newname exists,
it will be overwritten. If renaming a directory and
newname exists,
this function will emit a warning.
Parameters
-
oldname -
The old name.
Note:
The wrapper used in
oldnamemust match the wrapper used innewname. -
newname -
The new name.
-
context -
Note: Context support was added with PHP 5.0.0. For a description of
contexts, refer to Streams.
Return Values
Returns TRUE on success or FALSE on failure.
Changelog
| Version | Description |
|---|---|
| 5.3.1 | rename() can now rename files across drives in Windows. |
Examples
Example #1 Example with rename()
<?php
rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt");
?>
See Also
- copy() - Copies file
- unlink() - Deletes a file
- move_uploaded_file() - Moves an uploaded file to a new location
rewind
(PHP 4, PHP 5, PHP 7)
rewind — Rewind the position of a file pointer
Description
$handle
) : bool
Sets the file position indicator for handle
to the beginning of the file stream.
Note:
If you have opened the file in append ("a" or "a+") mode, any data you write to the file will always be appended, regardless of the file pointer position.
Parameters
-
handle -
The file pointer must be valid, and must point to a file successfully opened by fopen().
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 rewind() overwriting example
<?php
$handle = fopen('output.txt', 'r+');
fwrite($handle, 'Really long sentence.');
rewind($handle);
fwrite($handle, 'Foo');
rewind($handle);
echo fread($handle, filesize('output.txt'));
fclose($handle);
?>
The above example will output something similar to:
Foolly long sentence.
rmdir
(PHP 4, PHP 5, PHP 7)
rmdir — Removes directory
Description
$dirname
[, resource $context
] ) : bool
Attempts to remove the directory named by dirname.
The directory must be empty, and the relevant permissions must permit this.
A E_WARNING level error will be generated on failure.
Parameters
-
dirname -
Path to the directory.
-
context -
Note: Context support was added with PHP 5.0.0. For a description of
contexts, refer to Streams.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 rmdir() example
<?php
if (!is_dir('examples')) {
mkdir('examples');
}
rmdir('examples');
?>
Notes
Note: When safe mode is enabled, PHP checks whether the directory in which the script is operating has the same UID (owner) as the script that is being executed.
Description
This function is an alias of: stream_set_write_buffer().
stat
(PHP 4, PHP 5, PHP 7)
stat — Gives information about a file
Description
$filename
) : array
Gathers the statistics of the file named by
filename. If filename is a
symbolic link, statistics are from the file itself, not the symlink.
Prior to PHP 7.4.0, on Windows NTS builds the size,
atime, mtime and ctime
statistics have been from the symlink, in this case.
lstat() is identical to stat() except it would instead be based off the symlinks status.
Parameters
-
filename -
Path to the file.
Return Values
| Numeric | Associative | Description |
|---|---|---|
| 0 | dev | device number *** |
| 1 | ino | inode number **** |
| 2 | mode | inode protection mode |
| 3 | nlink | number of links |
| 4 | uid | userid of owner * |
| 5 | gid | groupid of owner * |
| 6 | rdev | device type, if inode device |
| 7 | size | size in bytes |
| 8 | atime | time of last access (Unix timestamp) |
| 9 | mtime | time of last modification (Unix timestamp) |
| 10 | ctime | time of last inode change (Unix timestamp) |
| 11 | blksize | blocksize of filesystem IO ** |
| 12 | blocks | number of 512-byte blocks allocated ** |
* On Windows this will always be 0.
** Only valid on systems supporting the st_blksize type - other
systems (e.g. Windows) return -1.
*** On Windows, as of PHP 7.4.0, this is the serial number of the volume that contains the file,
which is a 64-bit unsigned integer, so may overflow.
Previously, it was the numeric representation of the drive letter (e.g. 2
for C:) for stat(), and 0 for
lstat().
**** On Windows, as of PHP 7.4.0, this is the identifier associated with the file,
which is a 64-bit unsigned integer, so may overflow.
Previously, it was always 0.
The value of mode contains information read by several functions.
When written in octal, starting from the right, the first three digits are returned by
chmod(). The next digit is ignored by PHP. The next two digits indicate
the file type:
mode in octal |
Meaning |
|---|---|
0120000 |
link |
0100000 |
regular file |
0060000 |
block device |
0040000 |
directory |
0010000 |
fifo |
0100644 and a directory could be
0040755.
In case of error, stat() returns FALSE.
Note: Because PHP's integer type is signed and many platforms use 32bit integers, some filesystem functions may return unexpected results for files which are larger than 2GB.
Errors/Exceptions
Upon failure, an E_WARNING is emitted.
Changelog
| Version | Description |
|---|---|
| 7.4.0 | On Windows, the device number is now the serial number of the volume that contains the file, and the inode number is the identifier associated with the file. |
| 7.4.0 |
The size, atime, mtime and
ctime statistics of symlinks are always those of the target.
This was previously not the case for NTS builds on Windows.
|
Examples
Example #1 stat() example
<?php
/* Get file stat */
$stat = stat('C:\php\php.exe');
/*
* Print file access time, this is the same
* as calling fileatime()
*/
echo 'Access time: ' . $stat['atime'];
/*
* Print file modification time, this is the
* same as calling filemtime()
*/
echo 'Modification time: ' . $stat['mtime'];
/* Print the device number */
echo 'Device number: ' . $stat['dev'];
?>
Example #2 Using stat() information together with touch()
<?php
/* Get file stat */
$stat = stat('C:\php\php.exe');
/* Did we failed to get stat information? */
if (!$stat) {
echo 'stat() call failed...';
} else {
/*
* We want the access time to be 1 week
* after the current access time.
*/
$atime = $stat['atime'] + 604800;
/* Touch the file */
if (!touch('some_file.txt', time(), $atime)) {
echo 'Failed to touch file...';
} else {
echo 'touch() returned success...';
}
}
?>
Notes
Note:
Note that time resolution may differ from one file system to another.
Note: The results of this function are cached. See clearstatcache() for more details.
As of PHP 5.0.0, this function can also be used with some URL wrappers. Refer to Supported Protocols and Wrappers to determine which wrappers support stat() family of functionality.
See Also
- lstat() - Gives information about a file or symbolic link
- fstat() - Gets information about a file using an open file pointer
- filemtime() - Gets file modification time
- filegroup() - Gets file group
symlink
(PHP 4, PHP 5, PHP 7)
symlink — Creates a symbolic link
Description
$target
, string $link
) : bool
symlink() creates a symbolic link to the existing
target with the specified name
link.
Parameters
-
target -
Target of the link.
-
link -
The link name.
Return Values
Returns TRUE on success or FALSE on failure.
Changelog
| Version | Description |
|---|---|
| 5.3.0 | This function is now available on Windows platforms (Vista, Server 2008 or greater). |
Examples
Example #1 Create a symbolic link
<?php
$target = 'uploads.php';
$link = 'uploads';
symlink($target, $link);
echo readlink($link);
?>
Notes
Note: Windows users should note that this function will only work if the system you run PHP from is Windows Vista/Windows Server 2008 or newer. Windows versions prior to that do not support symbolic links.
See Also
- link() - Create a hard link
- readlink() - Returns the target of a symbolic link
- linkinfo() - Gets information about a link
tempnam
(PHP 4, PHP 5, PHP 7)
tempnam — Create file with unique file name
Description
$dir
, string $prefix
) : stringCreates a file with a unique filename, with access permission set to 0600, in the specified directory. If the directory does not exist or is not writable, tempnam() may generate a file in the system's temporary directory, and return the full path to that file, including its name.
Parameters
-
dir -
The directory where the temporary filename will be created.
-
prefix -
The prefix of the generated temporary filename.
Note: Only the first 63 characters of the prefix are used. Windows even uses only the first three characters of the prefix.
Return Values
Returns the new temporary filename (with path), or FALSE on
failure.
Examples
Example #1 tempnam() example
<?php
$tmpfname = tempnam("/tmp", "FOO");
$handle = fopen($tmpfname, "w");
fwrite($handle, "writing to tempfile");
fclose($handle);
// do here something
unlink($tmpfname);
?>
Notes
Note: If PHP cannot create a file in the specified
dirparameter, it falls back on the system default. On NTFS this also happens if the specifieddircontains more than 65534 files.
See Also
- tmpfile() - Creates a temporary file
- sys_get_temp_dir() - Returns directory path used for temporary files
- unlink() - Deletes a file
tmpfile
(PHP 4, PHP 5, PHP 7)
tmpfile — Creates a temporary file
Description
Creates a temporary file with a unique name in read-write (w+) mode and returns a file handle.
The file is automatically removed when closed (for example, by calling fclose(), or when there are no remaining references to the file handle returned by tmpfile()), or when the script ends.
If the script terminates unexpectedly, the temporary file may not be deleted.
Return Values
Returns a file handle, similar to the one returned by
fopen(), for the new file or FALSE on failure.
Examples
Example #1 tmpfile() example
<?php
$temp = tmpfile();
fwrite($temp, "writing to tempfile");
fseek($temp, 0);
echo fread($temp, 1024);
fclose($temp); // this removes the file
?>
The above example will output:
writing to tempfile
See Also
- tempnam() - Create file with unique file name
- sys_get_temp_dir() - Returns directory path used for temporary files
touch
(PHP 4, PHP 5, PHP 7)
touch — Sets access and modification time of file
Description
$filename
[, int $time = time()
[, int $atime
]] ) : bool
Attempts to set the access and modification times of the file named in the
filename parameter to the value given in
time.
Note that the access time is always modified, regardless of the number
of parameters.
If the file does not exist, it will be created.
Parameters
-
filename -
The name of the file being touched.
-
time -
The touch time. If
timeis not supplied, the current system time is used. -
atime -
If present, the access time of the given filename is set to the value of
atime. Otherwise, it is set to the value passed to thetimeparameter. If neither are present, the current system time is used.
Return Values
Returns TRUE on success or FALSE on failure.
Changelog
| Version | Description |
|---|---|
| 5.3.0 | It became possible to change the modification time of a directory under Windows. |
Examples
Example #1 touch() example
<?php
if (touch($filename)) {
echo $filename . ' modification time has been changed to present time';
} else {
echo 'Sorry, could not change modification time of ' . $filename;
}
?>
Example #2 touch() using the time parameter
<?php
// This is the touch time, we'll set it to one hour in the past.
$time = time() - 3600;
// Touch the file
if (!touch('some_file.txt', $time)) {
echo 'Whoops, something went wrong...';
} else {
echo 'Touched file with success';
}
?>
Notes
Note:
Note that time resolution may differ from one file system to another.
Prior to PHP 5.3.0 it was not possible to change the modification time of a directory with this function under Windows.
umask
(PHP 4, PHP 5, PHP 7)
umask — Changes the current umask
Description
$mask
] ) : int
umask() sets PHP's umask to
mask & 0777 and returns the old
umask. When PHP is being used as a server module, the umask
is restored when each request is finished.
Parameters
-
mask -
The new umask.
Return Values
umask() without arguments simply returns the current umask otherwise the old umask is returned.
Examples
Example #1 umask() example
<?php
$old = umask(0);
chmod("/path/some_dir/some_file.txt", 0755);
umask($old);
// Checking
if ($old != umask()) {
die('An error occurred while changing back the umask');
}
?>
Notes
Note:
Avoid using this function in multithreaded webservers. It is better to change the file permissions with chmod() after creating the file. Using umask() can lead to unexpected behavior of concurrently running scripts and the webserver itself because they all use the same umask.
unlink
(PHP 4, PHP 5, PHP 7)
unlink — Deletes a file
Description
$filename
[, resource $context
] ) : bool
Deletes filename. Similar to the Unix C unlink()
function. An E_WARNING level error will be generated on
failure.
Parameters
-
filename -
Path to the file.
-
context -
Note: Context support was added with PHP 5.0.0. For a description of
contexts, refer to Streams.
Return Values
Returns TRUE on success or FALSE on failure.
Changelog
| Version | Description |
|---|---|
| 7.3.0 | On Windows, it is now possible to unlink() files with handles in use, while formerly that would fail. However, it is still not possible to re-create the unlinked file, until all handles to it have been closed. |
Examples
Example #1 Basic unlink() usage
<?php
$fh = fopen('test.html', 'a');
fwrite($fh, '<h1>Hello world!</h1>');
fclose($fh);
unlink('test.html');
?>
Table of Contents
- basename — Returns trailing name component of path
- chgrp — Changes file group
- chmod — Changes file mode
- chown — Changes file owner
- clearstatcache — Clears file status cache
- copy — Copies file
- delete — See unlink or unset
- dirname — Returns a parent directory's path
- disk_free_space — Returns available space on filesystem or disk partition
- disk_total_space — Returns the total size of a filesystem or disk partition
- diskfreespace — Alias of disk_free_space
- fclose — Closes an open file pointer
- feof — Tests for end-of-file on a file pointer
- fflush — Flushes the output to a file
- fgetc — Gets character from file pointer
- fgetcsv — Gets line from file pointer and parse for CSV fields
- fgets — Gets line from file pointer
- fgetss — Gets line from file pointer and strip HTML tags
- file_exists — Checks whether a file or directory exists
- file_get_contents — Reads entire file into a string
- file_put_contents — Write data to a file
- file — Reads entire file into an array
- fileatime — Gets last access time of file
- filectime — Gets inode change time of file
- filegroup — Gets file group
- fileinode — Gets file inode
- filemtime — Gets file modification time
- fileowner — Gets file owner
- fileperms — Gets file permissions
- filesize — Gets file size
- filetype — Gets file type
- flock — Portable advisory file locking
- fnmatch — Match filename against a pattern
- fopen — Opens file or URL
- fpassthru — Output all remaining data on a file pointer
- fputcsv — Format line as CSV and write to file pointer
- fputs — Alias of fwrite
- fread — Binary-safe file read
- fscanf — Parses input from a file according to a format
- fseek — Seeks on a file pointer
- fstat — Gets information about a file using an open file pointer
- ftell — Returns the current position of the file read/write pointer
- ftruncate — Truncates a file to a given length
- fwrite — Binary-safe file write
- glob — Find pathnames matching a pattern
- is_dir — Tells whether the filename is a directory
- is_executable — Tells whether the filename is executable
- is_file — Tells whether the filename is a regular file
- is_link — Tells whether the filename is a symbolic link
- is_readable — Tells whether a file exists and is readable
- is_uploaded_file — Tells whether the file was uploaded via HTTP POST
- is_writable — Tells whether the filename is writable
- is_writeable — Alias of is_writable
- lchgrp — Changes group ownership of symlink
- lchown — Changes user ownership of symlink
- link — Create a hard link
- linkinfo — Gets information about a link
- lstat — Gives information about a file or symbolic link
- mkdir — Makes directory
- move_uploaded_file — Moves an uploaded file to a new location
- parse_ini_file — Parse a configuration file
- parse_ini_string — Parse a configuration string
- pathinfo — Returns information about a file path
- pclose — Closes process file pointer
- popen — Opens process file pointer
- readfile — Outputs a file
- readlink — Returns the target of a symbolic link
- realpath_cache_get — Get realpath cache entries
- realpath_cache_size — Get realpath cache size
- realpath — Returns canonicalized absolute pathname
- rename — Renames a file or directory
- rewind — Rewind the position of a file pointer
- rmdir — Removes directory
- set_file_buffer — Alias of stream_set_write_buffer
- stat — Gives information about a file
- symlink — Creates a symbolic link
- tempnam — Create file with unique file name
- tmpfile — Creates a temporary file
- touch — Sets access and modification time of file
- umask — Changes the current umask
- unlink — Deletes a file
- Introduction
- Installing/Configuring
- Predefined Constants
- Filesystem Functions
- basename — Returns trailing name component of path
- chgrp — Changes file group
- chmod — Changes file mode
- chown — Changes file owner
- clearstatcache — Clears file status cache
- copy — Copies file
- delete — See unlink or unset
- dirname — Returns a parent directory's path
- disk_free_space — Returns available space on filesystem or disk partition
- disk_total_space — Returns the total size of a filesystem or disk partition
- diskfreespace — Alias of disk_free_space
- fclose — Closes an open file pointer
- feof — Tests for end-of-file on a file pointer
- fflush — Flushes the output to a file
- fgetc — Gets character from file pointer
- fgetcsv — Gets line from file pointer and parse for CSV fields
- fgets — Gets line from file pointer
- fgetss — Gets line from file pointer and strip HTML tags
- file_exists — Checks whether a file or directory exists
- file_get_contents — Reads entire file into a string
- file_put_contents — Write data to a file
- file — Reads entire file into an array
- fileatime — Gets last access time of file
- filectime — Gets inode change time of file
- filegroup — Gets file group
- fileinode — Gets file inode
- filemtime — Gets file modification time
- fileowner — Gets file owner
- fileperms — Gets file permissions
- filesize — Gets file size
- filetype — Gets file type
- flock — Portable advisory file locking
- fnmatch — Match filename against a pattern
- fopen — Opens file or URL
- fpassthru — Output all remaining data on a file pointer
- fputcsv — Format line as CSV and write to file pointer
- fputs — Alias of fwrite
- fread — Binary-safe file read
- fscanf — Parses input from a file according to a format
- fseek — Seeks on a file pointer
- fstat — Gets information about a file using an open file pointer
- ftell — Returns the current position of the file read/write pointer
- ftruncate — Truncates a file to a given length
- fwrite — Binary-safe file write
- glob — Find pathnames matching a pattern
- is_dir — Tells whether the filename is a directory
- is_executable — Tells whether the filename is executable
- is_file — Tells whether the filename is a regular file
- is_link — Tells whether the filename is a symbolic link
- is_readable — Tells whether a file exists and is readable
- is_uploaded_file — Tells whether the file was uploaded via HTTP POST
- is_writable — Tells whether the filename is writable
- is_writeable — Alias of is_writable
- lchgrp — Changes group ownership of symlink
- lchown — Changes user ownership of symlink
- link — Create a hard link
- linkinfo — Gets information about a link
- lstat — Gives information about a file or symbolic link
- mkdir — Makes directory
- move_uploaded_file — Moves an uploaded file to a new location
- parse_ini_file — Parse a configuration file
- parse_ini_string — Parse a configuration string
- pathinfo — Returns information about a file path
- pclose — Closes process file pointer
- popen — Opens process file pointer
- readfile — Outputs a file
- readlink — Returns the target of a symbolic link
- realpath_cache_get — Get realpath cache entries
- realpath_cache_size — Get realpath cache size
- realpath — Returns canonicalized absolute pathname
- rename — Renames a file or directory
- rewind — Rewind the position of a file pointer
- rmdir — Removes directory
- set_file_buffer — Alias of stream_set_write_buffer
- stat — Gives information about a file
- symlink — Creates a symbolic link
- tempnam — Create file with unique file name
- tmpfile — Creates a temporary file
- touch — Sets access and modification time of file
- umask — Changes the current umask
- unlink — Deletes a file
Inotify
Introduction
The inotify extension exposes the inotify functions inotify_init(), inotify_add_watch() and inotify_rm_watch().
As the C inotify_init() function returns a file descriptor, PHP's inotify_init() returns a stream resource, usable with standard stream functions, like stream_select(), stream_set_blocking() and fclose(). inotify_read() replaces the C way of reading inotify events.
Installing/Configuring
Table of Contents
Requirements
This extension requires Linux 2.6.13 or newer, and a recent libC.
Installing/Configuring
This » PECL extension is not bundled with PHP.
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: » https://pecl.php.net/package/inotify.
Runtime Configuration
This extension has no configuration directives defined in php.ini.
Predefined Constants
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
-
Inotify constants usable with inotify_add_watch() and/or returned by inotify_read()
-
IN_ACCESS(integer) - File was accessed (read) (*)
-
IN_MODIFY(integer) - File was modified (*)
-
IN_ATTRIB(integer) - Metadata changed (e.g. permissions, mtime, etc.) (*)
-
IN_CLOSE_WRITE(integer) - File opened for writing was closed (*)
-
IN_CLOSE_NOWRITE(integer) - File not opened for writing was closed (*)
-
IN_OPEN(integer) - File was opened (*)
-
IN_MOVED_TO(integer) - File moved into watched directory (*)
-
IN_MOVED_FROM(integer) - File moved out of watched directory (*)
-
IN_CREATE(integer) - File or directory created in watched directory (*)
-
IN_DELETE(integer) - File or directory deleted in watched directory (*)
-
IN_DELETE_SELF(integer) - Watched file or directory was deleted
-
IN_MOVE_SELF(integer) - Watch file or directory was moved
-
IN_CLOSE(integer) - Equals to IN_CLOSE_WRITE | IN_CLOSE_NOWRITE
-
IN_MOVE(integer) - Equals to IN_MOVED_FROM | IN_MOVED_TO
-
IN_ALL_EVENTS(integer) - Bitmask of all the above constants
-
IN_UNMOUNT(integer) - File system containing watched object was unmounted
-
IN_Q_OVERFLOW(integer) - Event queue overflowed (wd is -1 for this event)
-
IN_IGNORED(integer) - Watch was removed (explicitly by inotify_rm_watch() or because file was removed or filesystem unmounted
-
IN_ISDIR(integer) - Subject of this event is a directory
-
IN_ONLYDIR(integer) - Only watch pathname if it is a directory (Since Linux 2.6.15)
-
IN_DONT_FOLLOW(integer) - Do not dereference pathname if it is a symlink (Since Linux 2.6.15)
-
IN_MASK_ADD(integer) - Add events to watch mask for this pathname if it already exists (instead of replacing mask).
-
IN_ONESHOT(integer) - Monitor pathname for one event, then remove from watch list.
Note: The events marked with an asterisk (*) above can occur for files in watched directories.
Inotify Functions
inotify_add_watch
(PECL inotify >= 0.1.2)
inotify_add_watch — Add a watch to an initialized inotify instance
Description
$inotify_instance
, string $pathname
, int $mask
) : int
inotify_add_watch() adds a new watch or modify an
existing watch for the file or directory specified in
pathname.
Using inotify_add_watch() on a watched object replaces
the existing watch. Using the IN_MASK_ADD constant
adds (OR) events to the existing watch.
Parameters
-
inotify_instance -
Resource returned by inotify_init()
-
pathname -
File or directory to watch
-
mask -
Events to watch for. See Predefined Constants.
Return Values
The return value is a unique (inotify instance wide) watch descriptor.
inotify_init
(PECL inotify >= 0.1.2)
inotify_init — Initialize an inotify instance
Description
Initialize an inotify instance for use with inotify_add_watch()
Return Values
A stream resource or FALSE on error.
Examples
Example #1 Example usage of inotify
<?php
// Open an inotify instance
$fd = inotify_init();
// Watch __FILE__ for metadata changes (e.g. mtime)
$watch_descriptor = inotify_add_watch($fd, __FILE__, IN_ATTRIB);
// generate an event
touch(__FILE__);
// Read events
$events = inotify_read($fd);
print_r($events);
// The following methods allows to use inotify functions without blocking on inotify_read():
// - Using stream_select() on $fd:
$read = array($fd);
$write = null;
$except = null;
stream_select($read,$write,$except,0);
// - Using stream_set_blocking() on $fd
stream_set_blocking($fd, 0);
inotify_read($fd); // Does no block, and return false if no events are pending
// - Using inotify_queue_len() to check if event queue is not empty
$queue_len = inotify_queue_len($fd); // If > 0, inotify_read() will not block
// Stop watching __FILE__ for metadata changes
inotify_rm_watch($fd, $watch_descriptor);
// Close the inotify instance
// This may have closed all watches if this was not already done
fclose($fd);
?>
The above example will output something similar to:
array(
array(
'wd' => 1, // Equals $watch_descriptor
'mask' => 4, // IN_ATTRIB bit is set
'cookie' => 0, // unique id to connect related events (e.g.
// IN_MOVE_FROM and IN_MOVE_TO events)
'name' => '', // the name of a file (e.g. if we monitored changes
// in a directory)
),
);
See Also
- inotify_add_watch() - Add a watch to an initialized inotify instance
- inotify_rm_watch() - Remove an existing watch from an inotify instance
- inotify_queue_len() - Return a number upper than zero if there are pending events
- inotify_read() - Read events from an inotify instance
- fclose() - Closes an open file pointer
inotify_queue_len
(PECL inotify >= 0.1.2)
inotify_queue_len — Return a number upper than zero if there are pending events
Description
$inotify_instance
) : intThis function allows to know if inotify_read() will block or not. If a number upper than zero is returned, there are pending events and inotify_read() will not block.
Return Values
Returns a number upper than zero if there are pending events.
See Also
- inotify_init() - Initialize an inotify instance
- stream_select() - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by tv_sec and tv_usec
- stream_set_blocking() - Set blocking/non-blocking mode on a stream
inotify_read
(PECL inotify >= 0.1.2)
inotify_read — Read events from an inotify instance
Description
$inotify_instance
) : arrayRead inotify events from an inotify instance.
Return Values
An array of inotify events or FALSE if no events was pending and
inotify_instance is non-blocking. Each event is an array with the following keys:
- wd is a watch descriptor returned by inotify_add_watch()
- mask is a bit mask of events
- cookie is a unique id to connect related events (e.g.
IN_MOVE_FROMandIN_MOVE_TO) - name is the name of a file (e.g. if a file was modified in a watched directory)
See Also
- inotify_init() - Initialize an inotify instance
- stream_select() - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by tv_sec and tv_usec
- stream_set_blocking() - Set blocking/non-blocking mode on a stream
- inotify_queue_len() - Return a number upper than zero if there are pending events
inotify_rm_watch
(PECL inotify >= 0.1.2)
inotify_rm_watch — Remove an existing watch from an inotify instance
Description
$inotify_instance
, int $watch_descriptor
) : bool
inotify_rm_watch() removes the watch
watch_descriptor from the inotify instance
inotify_instance.
Parameters
-
inotify_instance -
Resource returned by inotify_init()
-
watch_descriptor -
Watch to remove from the instance
Return Values
Returns TRUE on success or FALSE on failure.
Table of Contents
- inotify_add_watch — Add a watch to an initialized inotify instance
- inotify_init — Initialize an inotify instance
- inotify_queue_len — Return a number upper than zero if there are pending events
- inotify_read — Read events from an inotify instance
- inotify_rm_watch — Remove an existing watch from an inotify instance
- Introduction
- Installing/Configuring
- Predefined Constants
- Inotify Functions
- inotify_add_watch — Add a watch to an initialized inotify instance
- inotify_init — Initialize an inotify instance
- inotify_queue_len — Return a number upper than zero if there are pending events
- inotify_read — Read events from an inotify instance
- inotify_rm_watch — Remove an existing watch from an inotify instance
Mimetype
Introduction
This extension has been deprecated as the PECL extension Fileinfo provides the same functionality (and more) in a much cleaner way.
The functions in this module try to guess the content type and encoding of a file by looking for certain magic byte sequences at specific positions within the file. While this is not a bullet proof approach the heuristics used do a very good job.
This extension is derived from Apache mod_mime_magic, which is itself based on the file command maintained by Ian F. Darwin. See the source code for further historic and copyright information.
Installing/Configuring
Table of Contents
Requirements
No external libraries are needed to build this extension.
Installation
Mimetype extensions has been removed from PHP 5.3.0 in favor of Fileinfo.
You must compile PHP with the configure switch --with-mime-magic to get support for mime-type functions. The extension needs a copy of the simplified magic file that is distributed with the Apache httpd.
Note:
This extension is not capable of handling the fully decorated magic file that generally comes with standard Linux distro's and is supposed to be used with recent versions of file command.
Note: Note to Win32 Users
In order to use this module on a Windows environment, you must set the path to the bundled magic.mime file in your php.ini.
Example #1 Setting the path to magic.mime
mime_magic.magicfile = "$PHP_INSTALL_DIR\magic.mime"Remember to substitute the $PHP_INSTALL_DIR for your actual path to PHP in the above example. e.g. c:\php
Runtime Configuration
The behaviour of these functions is affected by settings in php.ini.
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| mime_magic.debug | "0" | PHP_INI_SYSTEM | Available since PHP 5.0.0. |
| mime_magic.magicfile | "/path/to/php/magic.mime" | PHP_INI_SYSTEM | Available since PHP 4.3.0. |
Here's a short explanation of the configuration directives.
Resource Types
This extension has no resource types defined.
Predefined Constants
This extension has no constants defined.
Phdfs
The phdfs extensions is using PHP to manipulate Hadoop HDFS phdfs requires PHP 5.3 or greater. Earlier versions may not work. For a quick start guide, please refer to the Tutorials section.
Installing/Configuring
Table of Contents
Requirements
PHP Version: PHP 5.3+
ZTS Enabled ( Thread Safety )
need to install hadoop
Installation
This » PECL extension is not bundled with PHP.
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: » https://pecl.php.net/package/phdfs.
This extension has no configuration directives defined in php.ini.
Resource Types
This extension has no resource types defined.
Predefined Constants
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
The phdfs class
(phdfs >= 0.1.0)
Introduction
Class synopsis
Properties
- host
- port
phdfs::connect
(phdfs >= 0.1.0)
phdfs::connect — Description
Description
This function is currently not documented; only its argument list is available.
Parameters
This function has no parameters.
Return Values
Returns TRUE on success or FALSE on failure.
phdfs::__construct
(phdfs >= 0.1.0)
phdfs::__construct — Description
Description
$ip
, string $port
)
This function is currently not documented; only its argument list is available.
Parameters
-
ip -
-
port -
Return Values
phdfs::copy
(phdfs >= 0.1.0)
phdfs::copy — Description
Description
$source_file
, string $destination_file
) : bool
This function is currently not documented; only its argument list is available.
Parameters
-
source_file -
-
destination_file -
Return Values
Returns TRUE on success or FALSE on failure.
phdfs::create_directory
(phdfs >= 0.1.0)
phdfs::create_directory — Description
Description
$path
) : bool
This function is currently not documented; only its argument list is available.
Parameters
-
path -
Return Values
Returns TRUE on success or FALSE on failure.
phdfs::delete
(phdfs >= 0.1.0)
phdfs::delete — Description
Description
$path
) : bool
This function is currently not documented; only its argument list is available.
Parameters
-
path -
Return Values
Returns TRUE on success or FALSE on failure.
phdfs::__destruct
(phdfs >= 0.1.0)
phdfs::__destruct — Description
Description
This function is currently not documented; only its argument list is available.
Parameters
This function has no parameters.
Return Values
No value is returned.
phdfs::disconnect
(phdfs >= 0.1.0)
phdfs::disconnect — Description
Description
This function is currently not documented; only its argument list is available.
Parameters
This function has no parameters.
Return Values
Returns TRUE on success or FALSE on failure.
phdfs::exists
(phdfs>= 0.1.0)
phdfs::exists — Description
Description
$path
) : bool
This function is currently not documented; only its argument list is available.
Parameters
-
path -
Return Values
Returns TRUE on success or FALSE on failure.
phdfs::file_info
(phdfs >= 0.1.0)
phdfs::file_info — Description
Description
$path
) : array
This function is currently not documented; only its argument list is available.
Parameters
-
path -
Return Values
Returns array on success or FALSE on failure.
phdfs::list_directory
(phdfs >= 0.1.0)
phdfs::list_directory — Description
Description
$path
[, int $level = 0
] ) : array
This function is currently not documented; only its argument list is available.
Parameters
-
path -
-
level -
Return Values
Returns array on success or FALSE on failure.
phdfs::read
(phdfs >= 0.1.0)
phdfs::read — Description
Description
$path
[, int $length = 0
] ) : string
This function is currently not documented; only its argument list is available.
Parameters
-
path -
-
length -
Return Values
phdfs::rename
(phdfs >= 0.1.0)
phdfs::rename — Description
Description
$old_path
, string $new_path
) : bool
This function is currently not documented; only its argument list is available.
Parameters
-
old_path -
-
new_path -
Return Values
Returns TRUE on success or FALSE on failure.
phdfs::tell
(phdfs >= 0.1.0)
phdfs::tell — Description
Description
$path
[, int $read_length = 1024
] ) : int
This function is currently not documented; only its argument list is available.
Parameters
-
path -
-
read_length -
Return Values
phdfs::write
(phdfs >= 0.1.0)
phdfs::write — Description
Description
$path
, string $buffer
[, int $mode = 0
] ) : bool
This function is currently not documented; only its argument list is available.
Parameters
-
path -
-
buffer -
-
mode -
Return Values
Returns TRUE on success or FALSE on failure.
Table of Contents
- phdfs::connect — Description
- phdfs::__construct — Description
- phdfs::copy — Description
- phdfs::create_directory — Description
- phdfs::delete — Description
- phdfs::__destruct — Description
- phdfs::disconnect — Description
- phdfs::exists — Description
- phdfs::file_info — Description
- phdfs::list_directory — Description
- phdfs::read — Description
- phdfs::rename — Description
- phdfs::tell — Description
- phdfs::write — Description
- Installing/Configuring
- Predefined Constants
- phdfs — The phdfs class
- phdfs::connect — Description
- phdfs::__construct — Description
- phdfs::copy — Description
- phdfs::create_directory — Description
- phdfs::delete — Description
- phdfs::__destruct — Description
- phdfs::disconnect — Description
- phdfs::exists — Description
- phdfs::file_info — Description
- phdfs::list_directory — Description
- phdfs::read — Description
- phdfs::rename — Description
- phdfs::tell — Description
- phdfs::write — Description
Proctitle
Introduction
This extension allows changing the current process', and thread, name on Linux and *BSD systems. This is useful when using pcntl_fork() to identify running processes in process list
Installing/Configuring
Table of Contents
Requirements
Nothing special.
Installation
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: » https://pecl.php.net/package/proctitle.
Runtime Configuration
This extension has no configuration directives defined in php.ini.
Resource Types
This extension has no resource types defined.
Predefined Constants
This extension has no constants defined.
Proctitle Functions
setproctitle
(PECL proctitle >= 0.1.0)
setproctitle — Set the process title
Description
$title
) : voidSets the process title of the current process.
Parameters
-
title -
The title to use as the process title.
Return Values
No value is returned.
Examples
Example #1 setproctitle() example
Running the example below will change the process title (visible with
ps a for example).
<?php
setproctitle("myscript");
?>
The above example will output something similar to:
$ ps a
PID TTY STAT TIME COMMAND
1168 pts/3 S 0:00 myscript
See Also
- cli_set_process_title() - Sets the process title
- pcntl_fork() - Forks the currently running process
- setthreadtitle() - Set the thread title
setthreadtitle
(PECL proctitle >= 0.1.2)
setthreadtitle — Set the thread title
Description
$title
) : boolSets the thread title.
Parameters
-
title -
The title to use as the thread title.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 setthreadtitle() example
Running the example below will change the thread title (visible with
ps c for example).
<?php
setthreadtitle("myscript");
?>
The above example will output something similar to:
$ ps c
PID TTY STAT TIME COMMAND
1178 pts/3 S 0:00 myscript
See Also
- pcntl_fork() - Forks the currently running process
- setproctitle() - Set the process title
Table of Contents
- setproctitle — Set the process title
- setthreadtitle — Set the thread title
- Introduction
- Installing/Configuring
- Predefined Constants
- Proctitle Functions
- setproctitle — Set the process title
- setthreadtitle — Set the thread title
xattr
Introduction
The xattr extension allows for the manipulation of extended attributes on a filesystem.
Installing/Configuring
Table of Contents
Requirements
To use xattr, you will need libattr installed. It is available at » http://savannah.nongnu.org/projects/attr/.
Note:
These functions only work on filesystems that support extended attributes, and have them enabled at mount time. Some common filesystems that support extended attributes are ext2, ext3, reiserfs, jfs, and xfs.
Installation
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: » https://pecl.php.net/package/xattr.
A DLL for this PECL extension is currently unavailable. See also the building on Windows section.
Runtime Configuration
This extension has no configuration directives defined in php.ini.
Resource Types
This extension has no resource types defined.
Predefined Constants
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
-
XATTR_ROOT(integer) - Set attribute in root (trusted) namespace. Requires root privileges.
-
XATTR_DONTFOLLOW(integer) - Do not follow the symbolic link but operate on symbolic link itself.
-
XATTR_CREATE(integer) - Function will fail if extended attribute already exists.
-
XATTR_REPLACE(integer) - Function will fail if extended attribute doesn't exist.
xattr Functions
xattr_get
(PECL xattr >= 0.9.0)
xattr_get — Get an extended attribute
Description
$filename
, string $name
[, int $flags = 0
] ) : stringThis function gets the value of an extended attribute of a file.
Extended attributes have two different namespaces: user
and root. The user namespace is available to all users, while the root namespace
is available only to users with root privileges. xattr operates on the user
namespace by default, but this can be changed with the
flags parameter.
Parameters
-
filename -
The file from which we get the attribute.
-
name -
The name of the attribute.
-
flags -
Supported xattr flags XATTR_DONTFOLLOWDo not follow the symbolic link but operate on symbolic link itself. XATTR_ROOTSet attribute in root (trusted) namespace. Requires root privileges.
Return Values
Returns a string containing the value or FALSE if the attribute doesn't
exist.
Examples
Example #1 Checks if system administrator has signed the file
<?php
$file = '/usr/local/sbin/some_binary';
$signature = xattr_get($file, 'Root signature', XATTR_ROOT);
/* ... check if $signature is valid ... */
?>
See Also
- xattr_list() - Get a list of extended attributes
- xattr_set() - Set an extended attribute
- xattr_remove() - Remove an extended attribute
xattr_list
(PECL xattr >= 0.9.0)
xattr_list — Get a list of extended attributes
Description
$filename
[, int $flags = 0
] ) : arrayThis functions gets a list of names of extended attributes of a file.
Extended attributes have two different namespaces: user
and root. The user namespace is available to all users, while the root namespace
is available only to users with root privileges. xattr operates on the user
namespace by default, but this can be changed with the
flags parameter.
Parameters
-
filename -
The path of the file.
-
flags -
Supported xattr flags XATTR_DONTFOLLOWDo not follow the symbolic link but operate on symbolic link itself. XATTR_ROOTSet attribute in root (trusted) namespace. Requires root privileges.
Return Values
This function returns an array with names of extended attributes.
Examples
Example #1 Prints names of all extended attributes of file
<?php
$file = 'some_file';
$root_attributes = xattr_list($file, XATTR_ROOT);
$user_attributes = xattr_list($file);
echo "Root attributes: \n";
foreach ($root_attributes as $attr_name) {
printf("%s\n", $attr_name);
}
echo "\n User attributes: \n";
foreach ($attributes as $attr_name) {
printf("%s\n", $attr_name);
}
?>
xattr_remove
(PECL xattr >= 0.9.0)
xattr_remove — Remove an extended attribute
Description
$filename
, string $name
[, int $flags = 0
] ) : boolThis function removes an extended attribute of a file.
Extended attributes have two different namespaces: user
and root. The user namespace is available to all users, while the root namespace
is available only to users with root privileges. xattr operates on the user
namespace by default, but this can be changed with the
flags parameter.
Parameters
-
filename -
The file from which we remove the attribute.
-
name -
The name of the attribute to remove.
-
flags -
Supported xattr flags XATTR_DONTFOLLOWDo not follow the symbolic link but operate on symbolic link itself. XATTR_ROOTSet attribute in root (trusted) namespace. Requires root privileges.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 Removes all extended attributes of a file
<?php
$file = 'some_file';
$attributes = xattr_list($file);
foreach ($attributes as $attr_name) {
xattr_remove($file, $attr_name);
}
?>
See Also
- xattr_list() - Get a list of extended attributes
- xattr_set() - Set an extended attribute
- xattr_get() - Get an extended attribute
xattr_set
(PECL xattr >= 0.9.0)
xattr_set — Set an extended attribute
Description
$filename
, string $name
, string $value
[, int $flags = 0
] ) : boolThis function sets the value of an extended attribute of a file.
Extended attributes have two different namespaces: user
and root. The user namespace is available to all users, while the root namespace
is available only to users with root privileges. xattr operates on the user
namespace by default, but this can be changed with the
flags parameter.
Parameters
-
filename -
The file in which we set the attribute.
-
name -
The name of the extended attribute. This attribute will be created if it doesn't exist or replaced otherwise. You can change this behaviour by using the
flagsparameter. -
value -
The value of the attribute.
-
flags -
Supported xattr flags XATTR_CREATEFunction will fail if extended attribute already exists. XATTR_REPLACEFunction will fail if extended attribute doesn't exist. XATTR_DONTFOLLOWDo not follow the symbolic link but operate on symbolic link itself. XATTR_ROOTSet attribute in root (trusted) namespace. Requires root privileges.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 Sets extended attributes on .wav file
<?php
$file = 'my_favourite_song.wav';
xattr_set($file, 'Artist', 'Someone');
xattr_set($file, 'My ranking', 'Good');
xattr_set($file, 'Listen count', '34');
/* ... other code ... */
printf("You've played this song %d times", xattr_get($file, 'Listen count'));
?>
xattr_supported
(PECL xattr >= 1.0.0)
xattr_supported — Check if filesystem supports extended attributes
Description
$filename
[, int $flags = 0
] ) : boolThis functions checks if the filesystem holding the given file supports extended attributes. Read access to the file is required.
Parameters
-
filename -
The path of the tested file.
-
flags -
Supported xattr flags XATTR_DONTFOLLOWDo not follow the symbolic link but operate on symbolic link itself.
Return Values
This function returns TRUE if filesystem supports extended attributes,
FALSE if it doesn't and NULL if it can't be determined (for example
wrong path or lack of permissions to file).
Examples
Example #1 xattr_supported() example
The following code checks if we can use extended attributes.
<?php
$file = 'some_file';
if (xattr_supported($file)) {
/* ... make use of some xattr_* functions ... */
}
?>
Table of Contents
- xattr_get — Get an extended attribute
- xattr_list — Get a list of extended attributes
- xattr_remove — Remove an extended attribute
- xattr_set — Set an extended attribute
- xattr_supported — Check if filesystem supports extended attributes
- Introduction
- Installing/Configuring
- Predefined Constants
- xattr Functions
- xattr_get — Get an extended attribute
- xattr_list — Get a list of extended attributes
- xattr_remove — Remove an extended attribute
- xattr_set — Set an extended attribute
- xattr_supported — Check if filesystem supports extended attributes
xdiff
Introduction
xdiff extension enables you to create and apply patch files containing differences between different revisions of files.
This extension supports two modes of operation - on strings and on files, as well as two different patch formats - unified and binary. Unified patches are excellent for text files as they are human-readable and easy to review. For binary files like archives or images, binary patches will be adequate choice as they are binary safe and handle non-printable characters well.
Starting from version 1.5.0 there are two different sets of functions for generating binary patches. New functions - xdiff_string_rabdiff() and xdiff_file_rabdiff() generate output compatible with older functions but are typically faster and generate smaller results. For more details about methods of generating binary patches and differences between them, please check » libxdiff website.
This extension uses libxdiff to implement these functions. Please see » http://www.xmailserver.org/xdiff-lib.html for more information.
Installing/Configuring
Table of Contents
Requirements
To use xdiff, you will need libxdiff installed, available on the libxdiff homepage » http://www.xmailserver.org/xdiff-lib.html.
Note:
You'll need at least libxdiff 0.7 for these functions to be aware of memory_limit.
Installation
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: » https://pecl.php.net/package/xdiff.
A DLL for this PECL extension is currently unavailable. See also the building on Windows section.
Runtime Configuration
This extension has no configuration directives defined in php.ini.
Resource Types
This extension has no resource types defined.
Predefined Constants
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
-
XDIFF_PATCH_NORMAL(integer) - This flag indicates that xdiff_string_patch() and xdiff_file_patch() functions should create result by applying patch to original content thus creating newer version of file. This is the default mode of operation.
-
XDIFF_PATCH_REVERSE(integer) - This flag indicated that xdiff_string_patch() and xdiff_file_patch() functions should create result by reversing patch changed from newer content thus creating original version.
xdiff Functions
xdiff_file_bdiff_size
(PECL xdiff >= 1.5.0)
xdiff_file_bdiff_size — Read a size of file created by applying a binary diff
Description
$file
) : int
Returns a size of a result file that would be created after applying binary patch from file
file to the original file.
Parameters
-
file -
The path to the binary patch created by xdiff_string_bdiff() or xdiff_string_rabdiff() function.
Return Values
Returns the size of file that would be created.
Examples
Example #1 xdiff_file_bdiff_size() example
The following code applies reads a size of file that would be created after applying a binary diff.
<?php
$length = xdiff_string_bdiff_size('file.bdiff');
echo "Resulting file will be $length bytes long";
?>
See Also
- xdiff_file_bdiff() - Make binary diff of two files
- xdiff_file_rabdiff() - Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm
- xdiff_file_bpatch() - Patch a file with a binary diff
xdiff_file_bdiff
(PECL xdiff >= 1.5.0)
xdiff_file_bdiff — Make binary diff of two files
Description
$old_file
, string $new_file
, string $dest
) : boolMakes a binary diff of two files and stores the result in a patch file. This function works with both text and binary files. Resulting patch file can be later applied using xdiff_file_bpatch()/xdiff_string_bpatch().
Parameters
-
old_file -
Path to the first file. This file acts as "old" file.
-
new_file -
Path to the second file. This file acts as "new" file.
-
dest -
Path of the resulting patch file. Resulting file contains differences between "old" and "new" files. It is in binary format and is human-unreadable.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 xdiff_file_bdiff() example
The following code makes binary diff of two archives.
<?php
$old_version = 'my_script_1.0.tgz';
$new_version = 'my_script_1.1.tgz';
xdiff_file_bdiff($old_version, $new_version, 'my_script.bdiff');
?>
Notes
Note:
Both files will be loaded into memory so ensure that your memory_limit is set high enough.
xdiff_file_bpatch
(PECL xdiff >= 1.5.0)
xdiff_file_bpatch — Patch a file with a binary diff
Description
$file
, string $patch
, string $dest
) : bool
Patches a file with a binary
patch and stores the result in a file dest.
This function accepts patches created both via xdiff_file_bdiff()
and xdiff_file_rabdiff() functions or their string counterparts.
Parameters
-
file -
The original file.
-
patch -
The binary patch file.
-
dest -
Path of the resulting file.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 xdiff_file_bpatch() example
The following code applies binary diff to a file.
<?php
$old_version = 'archive-1.0.tgz';
$patch = 'archive.bpatch';
$result = xdiff_file_bpatch($old_version, $patch, 'archive-1.1.tgz');
if ($result) {
echo "File patched";
} else {
echo "File couldn't be patched";
}
?>
Notes
Note:
Both files (
fileandpatch) will be loaded into memory so ensure that your memory_limit is set high enough.
See Also
- xdiff_file_bdiff() - Make binary diff of two files
- xdiff_file_rabdiff() - Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm
xdiff_file_diff_binary
(PECL xdiff >= 0.2.0)
xdiff_file_diff_binary — Alias of xdiff_file_bdiff
Description
$old_file
, string $new_file
, string $dest
) : boolMakes a binary diff of two files and stores the result in a patch file. This function works with both text and binary files. Resulting patch file can be later applied using xdiff_file_bpatch().
Starting with version 1.5.0 this function is an alias of xdiff_file_bdiff().
Parameters
-
old_file -
Path to the first file. This file acts as "old" file.
-
new_file -
Path to the second file. This file acts as "new" file.
-
dest -
Path of the resulting patch file. Resulting file contains differences between "old" and "new" files. It is in binary format and is human-unreadable.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 xdiff_file_diff_binary() example
The following code makes binary diff of two archives.
<?php
$old_version = 'my_script_1.0.tgz';
$new_version = 'my_script_1.1.tgz';
xdiff_file_diff_binary($old_version, $new_version, 'my_script.bdiff');
?>
Notes
Note:
Both files will be loaded into memory so ensure that your memory_limit is set high enough.
See Also
- xdiff_file_bdiff() - Make binary diff of two files
- xdiff_file_bpatch() - Patch a file with a binary diff
xdiff_file_diff
(PECL xdiff >= 0.2.0)
xdiff_file_diff — Make unified diff of two files
Description
$old_file
, string $new_file
, string $dest
[, int $context = 3
[, bool $minimal = FALSE
]] ) : bool
Makes an unified diff containing differences between old_file and
new_file and stores it in dest file. The
resulting file is human-readable. An optional context parameter
specifies how many lines of context should be added around each change.
Setting minimal parameter to true will result in outputting the shortest
patch file possible (can take a long time).
Parameters
-
old_file -
Path to the first file. This file acts as "old" file.
-
new_file -
Path to the second file. This file acts as "new" file.
-
dest -
Path of the resulting patch file.
-
context -
Indicates how many lines of context you want to include in diff result.
-
minimal -
Set this parameter to
TRUEif you want to minimalize size of the result (can take a long time).
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 xdiff_file_diff() example
The following code makes unified diff of two php files with context length of 2.
<?php
$old_version = 'my_script.php';
$new_version = 'my_new_script.php';
xdiff_file_diff($old_version, $new_version, 'my_script.diff', 2);
?>
Notes
Note:
This function doesn't work well with binary files. To make diff of binary files use xdiff_file_bdiff()/xdiff_file_rabdiff() function.
xdiff_file_merge3
(PECL xdiff >= 0.2.0)
xdiff_file_merge3 — Merge 3 files into one
Description
$old_file
, string $new_file1
, string $new_file2
, string $dest
) : mixed
Merges three files into one and stores the result in a file dest.
The old_file is an original version while new_file1
and new_file2 are modified versions of an original.
Parameters
-
old_file -
Path to the first file. It acts as "old" file.
-
new_file1 -
Path to the second file. It acts as modified version of
old_file. -
new_file2 -
Path to the third file. It acts as modified version of
old_file. -
dest -
Path of the resulting file, containing merged changed from both
new_file1andnew_file2.
Return Values
Returns TRUE if merge was successful, string with rejected chunks if
it was not or FALSE if an internal error happened.
Examples
Example #1 xdiff_file_merge3() example
The following code merges three files into one.
<?php
$old_version = 'original_script.php';
$fix1 = 'script_with_fix1.php';
$fix2 = 'script_with_fix2.php';
$errors = xdiff_file_merge3($old_version, $fix1, $fix2, 'fixed_script.php');
if (is_string($errors)) {
echo "Rejects:\n";
echo $errors;
}
?>
xdiff_file_patch_binary
(PECL xdiff >= 0.2.0)
xdiff_file_patch_binary — Alias of xdiff_file_bpatch
Description
$file
, string $patch
, string $dest
) : bool
Patches a file with a binary
patch and stores the result in a file dest.
This function accepts patches created both via xdiff_file_bdiff()
or xdiff_file_rabdiff() functions or their string counterparts.
Starting with version 1.5.0 this function is an alias of xdiff_file_bpatch().
Parameters
-
file -
The original file.
-
patch -
The binary patch file.
-
dest -
Path of the resulting file.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 xdiff_file_patch_binary() example
The following code applies binary diff to a file.
<?php
$old_version = 'archive-1.0.tgz';
$patch = 'archive.bpatch';
$result = xdiff_file_patch_binary($old_version, $patch, 'archive-1.1.tgz');
if ($result) {
echo "File patched";
} else {
echo "File couldn't be patched";
}
?>
Notes
Note:
Both files (
fileandpatch) will be loaded into memory so ensure that your memory_limit is set high enough.
xdiff_file_patch
(PECL xdiff >= 0.2.0)
xdiff_file_patch — Patch a file with an unified diff
Description
$file
, string $patch
, string $dest
[, int $flags = DIFF_PATCH_NORMAL
] ) : mixed
Patches a file with a patch and stores the result in a file.
patch has to be an unified diff created by
xdiff_file_diff()/xdiff_string_diff() function.
An optional flags parameter specifies mode of operation.
Parameters
-
file -
The original file.
-
patch -
The unified patch file. It has to be created using xdiff_string_diff(), xdiff_file_diff() functions or compatible tools.
-
dest -
Path of the resulting file.
-
flags -
Can be either
XDIFF_PATCH_NORMAL(default mode, normal patch) orXDIFF_PATCH_REVERSE(reversed patch).Starting from version 1.5.0, you can also use binary OR to enable
XDIFF_PATCH_IGNORESPACEflag.
Return Values
Returns FALSE if an internal error happened, string with rejected
chunks if patch couldn't be applied or TRUE if patch has been successfully applied.
Examples
Example #1 xdiff_file_patch() example
The following code applies unified diff to a file.
<?php
$old_version = 'my_script-1.0.php';
$patch = 'my_script.patch';
$errors = xdiff_file_patch($old_version, $patch, 'my_script-1.1.php');
if (is_string($errors)) {
echo "Rejects:\n";
echo $errors;
}
?>
Example #2 Patch reversing example
The following code reverses a patch.
<?php
$new_version = 'my_script-1.1.php';
$patch = 'my_script.patch';
$errors = xdiff_file_patch($new_version, $patch, 'my_script-1.0.php', XDIFF_PATCH_REVERSE);
if (is_string($errors)) {
echo "Rejects:\n";
echo $errors;
}
?>
xdiff_file_rabdiff
(PECL xdiff >= 1.5.0)
xdiff_file_rabdiff — Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm
Description
$old_file
, string $new_file
, string $dest
) : boolMakes a binary diff of two files and stores the result in a patch file. The difference between this function and xdiff_file_bdiff() is different algorithm used which should result in faster execution and smaller diff produced. This function works with both text and binary files. Resulting patch file can be later applied using xdiff_file_bpatch()/xdiff_string_bpatch().
For more details about differences between algorithm used please check » libxdiff website.
Parameters
-
old_file -
Path to the first file. This file acts as "old" file.
-
new_file -
Path to the second file. This file acts as "new" file.
-
dest -
Path of the resulting patch file. Resulting file contains differences between "old" and "new" files. It is in binary format and is human-unreadable.
Return Values
Returns TRUE on success or FALSE on failure.
Examples
Example #1 xdiff_file_rabdiff() example
The following code makes binary diff of two archives.
<?php
$old_version = 'my_script_1.0.tgz';
$new_version = 'my_script_1.1.tgz';
xdiff_file_rabdiff($old_version, $new_version, 'my_script.bdiff');
?>
Notes
Note:
Both files will be loaded into memory so ensure that your memory_limit is set high enough.
xdiff_string_bdiff_size
(PECL xdiff >= 1.5.0)
xdiff_string_bdiff_size — Read a size of file created by applying a binary diff
Description
$patch
) : int
Returns a size of a result file that would be created after applying binary patch to
the original file.
Parameters
-
patch -
The binary patch created by xdiff_string_bdiff() or xdiff_string_rabdiff() function.
Return Values
Returns the size of file that would be created.
Examples
Example #1 xdiff_string_bdiff_size() example
The following code applies reads a size of file that would be created after applying a binary diff.
<?php
$binary_patch = file_get_contents('file.bdiff');
$length = xdiff_string_bdiff_size($binary_patch);
echo "Resulting file will be $length bytes long";
?>
See Also
- xdiff_string_bdiff() - Make binary diff of two strings
- xdiff_string_rabdiff() - Make binary diff of two strings using the Rabin's polynomial fingerprinting algorithm
- xdiff_string_bpatch() - Patch a string with a binary diff
xdiff_string_bdiff
(PECL xdiff >= 1.5.0)
xdiff_string_bdiff — Make binary diff of two strings
Description
$old_data
, string $new_data
) : stringMakes a binary diff of two strings and returns the result. This function works with both text and binary data. Resulting patch can be later applied using xdiff_string_bpatch()/xdiff_file_bpatch().
Parameters
-
old_data -
First string with binary data. It acts as "old" data.
-
new_data -
Second string with binary data. It acts as "new" data.
Return Values
Returns string with binary diff containing differences between "old" and "new"
data or FALSE if an internal error occurred.
xdiff_string_bpatch
(PECL xdiff >= 1.5.0)
xdiff_string_bpatch — Patch a string with a binary diff
Description
$str
, string $patch
) : string
Patches a string str with a binary patch.
This function accepts patches created both via xdiff_string_bdiff()
and xdiff_string_rabdiff() functions or their file counterparts.
Parameters
-
str -
The original binary string.
-
patch -
The binary patch string.
Return Values
Returns the patched string, or FALSE on error.
See Also
- xdiff_string_bdiff() - Make binary diff of two strings
- xdiff_string_rabdiff() - Make binary diff of two strings using the Rabin's polynomial fingerprinting algorithm
xdiff_string_diff_binary
(PECL xdiff >= 0.2.0)
xdiff_string_diff_binary — Alias of xdiff_string_bdiff
Description
Makes a binary diff of two strings and returns the result. This function works with both text and binary data. Resulting patch can be later applied using xdiff_string_bpatch()/xdiff_file_bpatch().
Starting with version 1.5.0 this function is an alias of xdiff_string_bdiff().
Parameters
-
old_data -
First string with binary data. It acts as "old" data.
-
new_data -
Second string with binary data. It acts as "new" data.
Return Values
Returns string with result or FALSE if an internal error happened.
See Also
- xdiff_string_bdiff() - Make binary diff of two strings
- xdiff_string_bpatch() - Patch a string with a binary diff
xdiff_string_diff
(PECL xdiff >= 0.2.0)
xdiff_string_diff — Make unified diff of two strings
Description
$old_data
, string $new_data
[, int $context = 3
[, bool $minimal = FALSE
]] ) : string
Makes an unified diff containing differences between old_data string and
new_data string and returns it. The resulting diff is human-readable.
An optional context parameter specifies how many lines of context should be
added around each change. Setting minimal parameter
to true will result in outputting the shortest patch file possible (can take a long time).
Parameters
-
old_data -
First string with data. It acts as "old" data.
-
new_data -
Second string with data. It acts as "new" data.
-
context -
Indicates how many lines of context you want to include in the diff result.
-
minimal -
Set this parameter to
TRUEif you want to minimalize the size of the result (can take a long time).
Return Values
Returns string with resulting diff or FALSE if an internal error happened.
Examples
Example #1 xdiff_string_diff() example
The following code makes unified diff of two articles.
<?php
$old_article = file_get_contents('./old_article.txt');
$new_article = $_REQUEST['article']; /* Let's say that someone pasted a new article to html form */
$diff = xdiff_string_diff($old_article, $new_article, 1);
if (is_string($diff)) {
echo "Differences between two articles:\n";
echo $diff;
}
?>
Notes
Note:
This function doesn't work well with binary strings. To make diff of binary strings use xdiff_string_bdiff()/xdiff_string_rabdiff().
xdiff_string_merge3
(PECL xdiff >= 0.2.0)
xdiff_string_merge3 — Merge 3 strings into one
Description
$old_data
, string $new_data1
, string $new_data2
[, string &$error
] ) : mixed
Merges three strings into one and returns the result.
The old_data is an original version of data
while new_data1 and new_data2 are modified
versions of an original. An optional error is used to pass any
rejected parts during merging process.
Parameters
-
old_data -
First string with data. It acts as "old" data.
-
new_data1 -
Second string with data. It acts as modified version of
old_data. -
new_data2 -
Third string with data. It acts as modified version of
old_data. -
error -
If provided then rejected parts are stored inside this variable.
Return Values
Returns the merged string, FALSE if an internal error happened, or TRUE
if merged string is empty.
xdiff_string_patch_binary
(PECL xdiff >= 0.2.0)
xdiff_string_patch_binary — Alias of xdiff_string_bpatch
Description
$str
, string $patch
) : string
Patches a string str with a binary patch.
This function accepts patches created both via xdiff_string_bdiff()
and xdiff_string_rabdiff() functions or their file counterparts.
Starting with version 1.5.0 this function is an alias of xdiff_string_bpatch().
Parameters
-
str -
The original binary string.
-
patch -
The binary patch string.
Return Values
Returns the patched string, or FALSE on error.
See Also
- xdiff_string_bpatch() - Patch a string with a binary diff
- xdiff_string_bdiff() - Make binary diff of two strings
- xdiff_string_rabdiff() - Make binary diff of two strings using the Rabin's polynomial fingerprinting algorithm
xdiff_string_patch
(PECL xdiff >= 0.2.0)
xdiff_string_patch — Patch a string with an unified diff
Description
$str
, string $patch
[, int $flags
[, string &$error
]] ) : string
Patches a str string with an unified patch in patch parameter
and returns the result. patch has to be an unified diff created by
xdiff_file_diff()/xdiff_string_diff() function.
An optional flags parameter specifies mode of operation. Any
rejected parts of the patch will be stored inside error variable if
it is provided.
Parameters
-
str -
The original string.
-
patch -
The unified patch string. It has to be created using xdiff_string_diff(), xdiff_file_diff() functions or compatible tools.
-
flags -
flagscan be eitherXDIFF_PATCH_NORMAL(default mode, normal patch) orXDIFF_PATCH_REVERSE(reversed patch).Starting from version 1.5.0, you can also use binary OR to enable
XDIFF_PATCH_IGNORESPACEflag. -
error -
If provided then rejected parts are stored inside this variable.
Return Values
Returns the patched string, or FALSE on error.
Examples
Example #1 xdiff_string_patch() example
The following code applies changes to some article.
<?php
$old_article = file_get_contents('./old_article.txt');
$diff = $_SERVER['patch']; /* Let's say that someone pasted a patch to html form */
$errors = '';
$new_article = xdiff_string_patch($old_article, $diff, XDIFF_PATCH_NORMAL, $errors);
if (is_string($new_article)) {
echo "New article:\n";
echo $new_article;
}
if (strlen($errors)) {
echo "Rejects: \n";
echo $errors;
}
?>
xdiff_string_rabdiff
(PECL xdiff >= 1.5.0)
xdiff_string_rabdiff — Make binary diff of two strings using the Rabin's polynomial fingerprinting algorithm
Description
Makes a binary diff of two strings and returns the result. The difference between this function and xdiff_string_bdiff() is different algorithm used which should result in faster execution and smaller diff produced. This function works with both text and binary data. Resulting patch can be later applied using xdiff_string_bpatch()/xdiff_file_bpatch().
For more details about differences between algorithm used please check » libxdiff website.
Parameters
-
old_data -
First string with binary data. It acts as "old" data.
-
new_data -
Second string with binary data. It acts as "new" data.
Return Values
Returns string with binary diff containing differences between "old" and "new"
data or FALSE if an internal error occurred.
Table of Contents
- xdiff_file_bdiff_size — Read a size of file created by applying a binary diff
- xdiff_file_bdiff — Make binary diff of two files
- xdiff_file_bpatch — Patch a file with a binary diff
- xdiff_file_diff_binary — Alias of xdiff_file_bdiff
- xdiff_file_diff — Make unified diff of two files
- xdiff_file_merge3 — Merge 3 files into one
- xdiff_file_patch_binary — Alias of xdiff_file_bpatch
- xdiff_file_patch — Patch a file with an unified diff
- xdiff_file_rabdiff — Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm
- xdiff_string_bdiff_size — Read a size of file created by applying a binary diff
- xdiff_string_bdiff — Make binary diff of two strings
- xdiff_string_bpatch — Patch a string with a binary diff
- xdiff_string_diff_binary — Alias of xdiff_string_bdiff
- xdiff_string_diff — Make unified diff of two strings
- xdiff_string_merge3 — Merge 3 strings into one
- xdiff_string_patch_binary — Alias of xdiff_string_bpatch
- xdiff_string_patch — Patch a string with an unified diff
- xdiff_string_rabdiff — Make binary diff of two strings using the Rabin's polynomial fingerprinting algorithm
- Introduction
- Installing/Configuring
- Predefined Constants
- xdiff Functions
- xdiff_file_bdiff_size — Read a size of file created by applying a binary diff
- xdiff_file_bdiff — Make binary diff of two files
- xdiff_file_bpatch — Patch a file with a binary diff
- xdiff_file_diff_binary — Alias of xdiff_file_bdiff
- xdiff_file_diff — Make unified diff of two files
- xdiff_file_merge3 — Merge 3 files into one
- xdiff_file_patch_binary — Alias of xdiff_file_bpatch
- xdiff_file_patch — Patch a file with an unified diff
- xdiff_file_rabdiff — Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm
- xdiff_string_bdiff_size — Read a size of file created by applying a binary diff
- xdiff_string_bdiff — Make binary diff of two strings
- xdiff_string_bpatch — Patch a string with a binary diff
- xdiff_string_diff_binary — Alias of xdiff_string_bdiff
- xdiff_string_diff — Make unified diff of two strings
- xdiff_string_merge3 — Merge 3 strings into one
- xdiff_string_patch_binary — Alias of xdiff_string_bpatch
- xdiff_string_patch — Patch a string with an unified diff
- xdiff_string_rabdiff — Make binary diff of two strings using the Rabin's polynomial fingerprinting algorithm
- Direct IO
- Directories
- Installing/Configuring
- Predefined Constants
- Directory — The Directory class
- Directory Functions
- Fileinfo — File Information
- Filesystem
- Inotify
- Mimetype
- Phdfs
- Installing/Configuring
- Predefined Constants
- phdfs — The phdfs class
- Proctitle
- xattr
- xdiff